draft-hunt-idevent-distribution.xml

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-hunt-idevent-distribution-01"
	ipr="trust200902">
	<front>
		<title abbrev="draft-hunt-idevent-distribution">
			SET Token Distribution and Subscription Management Profile</title>

		<author fullname="Phil Hunt" initials="P." role="editor"
			surname="Hunt">
			<organization abbrev="Oracle">Oracle Corporation</organization>

			<address>
				<email>phil.hunt@yahoo.com</email>
			</address>
		</author>
    
    <author fullname="Marius Scurtescu" initials="M.S." surname="Scurtescu">
      <organization abbrev="Google">Google</organization>

      <address>
        <email>mscurtescu@google.com</email>
      </address>
    </author>
    

		<author fullname="Morteza Ansari" initials="M.A." surname="Ansari">
			<organization abbrev="Cisco">Cisco</organization>

			<address>
				<email>morteza.ansari@cisco.com</email>
			</address>
		</author>

		<date year="2016" />

		<keyword>Internet-Draft</keyword>

		<abstract>
			<t>
				The specification defines how a subscriber to a feed of security 
        events (SETs) may query for, subscribe and receive SETs from a
        security event feed. The specification defines
        a single mandatory-to-implement method using HTTP Post to deliver 
        events to registered subscribers and a registry for new methods. </t>
		</abstract>
	</front>

	<middle>
		<section anchor="intro" title="Introduction and Overview" toc="default">
			
      <t>
        This specification defines a method by which SETs (see <xref target="I-D.hunt-idevent-token"/>)
        can be delivered by publishers to feed subscribers using HTTP POST 
        <xref target="RFC7231"/> as well as an extension registry enabling
        other methods of delivery. This specification also defines how 
        subscribers MAY query for available Feeds, and 
        manage event Subscriptions using SCIM <xref target="RFC7644"/>. 
			</t>

			<figure anchor="notificationArch" title="Subscription Management and Delivery">
          <preamble>The following diagram shows a typical SET Feed
        Provider and the services provided to Subscribers. Arrow heads point
        to the service provider (the direction of an HTTP request):</preamble>
					<artwork align="center">
+------------+                        +-------------+
|            |Feeds Catalog           |             |
|            &lt;------------------------+             |
|   SCIM     |                        |    SET      |
|   Feed     |Subscription Request    |    Feed     |
|   Mgmt     &lt;------------------------+  Subscriber |
|            |                        |             |
|            |Subscription Mgmt       |             |
|            &lt;------------------------+             |
|            |                        |             |
+------------+                        |             |
+------------+                        |             |
|            |                        |             |
|   FEED     |SET Delivery            |             |
|            +------------------------>             |
|  Provider  |                        |             | 
|            |                        |             |
+------------+                        +-------------+
</artwork>
			</figure>

			<t>A SET Feed Provider MAY be directly integrated into a source
				service that generates events, or it may be a separate service entity 
        that off-loads event distribution from the event generator to act 
        as its delegated publisher. For the purposes of this specification, 
        while SET	distribution may be handled separately, this specification will 
        consider the method for how event generators send events to publishers
        as out-of-scope.
			</t>
      
      <t>The specification uses SCIM protocol <xref target="RFC7644"/> to advertise available Feeds
      and to enable Subscribers to request, subscriber to, and manage
      Subscriptions.</t>
     
      <t>The specification defines a registry by which multiple SET delivery
      methods can be registered. The specification includes a web callback 
      method which uses HTTP POST <xref target="RFC7231"/> to deliver SETs 
      to Subscribers.</t>

			<section anchor="notat" title="Notational Conventions" toc="default">
				<t>
					The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
					"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
					this
					document are to be interpreted as described in
					<xref target="RFC2119" />
					. These keywords are capitalized when used to
					unambiguously specify requirements of the protocol or application
					features and behavior that affect the inter-operability and security of
					implementations. When these words are not capitalized, they are
					meant
					in their natural-language sense.
				</t>

				<t>
					For purposes of readability examples are not URL encoded.
					Implementers MUST percent encode URLs as described in
					<xref target="RFC3986">Section 2.1 of</xref>
					.
				</t>

				<t>Throughout this documents all figures MAY contain spaces and
					extra
					line-wrapping for readability and space limitations. Similarly, some
					URI's contained within examples, have been shortened for space and
					readability reasons.
				</t>
			</section>

			<section anchor="defs" title="Definitions" toc="default">
        <t>This specification assumes terminology defined in the Security
        Event Token specification<xref target="I-D.hunt-idevent-token"/>.</t>
				<t>
					The following definitions are specific to Identity Event
					publishing:
					<list style="hanging">
						<t hangText="Feed Provider"><vspace/>The Feed Provider publishes
							SETs to be distributed to registered subscribers.
						</t>

						<t hangText="Feed"><vspace/>A Feed is a URI that describes the set of
							resources and events under which events may be issued. An
							interested subscriber registers with the feed provider to subscribe
							to an event URI to receive SETs associated with a Feed. An
              individual Feed MAY have zero or more Subscriptions.
						</t>
            
            <t hangText="Subscription"><vspace/>A Subscription contains the information
            needed by a Feed Provider (e.g. delivery endpoints, credentials)
            to deliver a Feed of SETs to an individual Subscriber. A 
            Subscription has ONE Feed.</t>

						<t hangText="Notification Mechanism"><vspace/>
							A URI that describes the
							chosen event notification mechanism. When subscribing to a feed, a
							client may choose a specific mechanism by which it wishes to
							receive notification events. 
						</t>

						<t hangText="Subscriber"><vspace/>A Subscriber is an party or
            security entity registers in the form of a Subscription to 
            receive SETs from a feed provider that are part of a Feed. 
						</t>
					</list>
				</t>
			</section>
		</section>

		<section anchor="process" title="Event Notification Process">
			<t>When a Security Event occurs, the Feed Provider constructs a SET
      token <xref target="I-D.hunt-idevent-token"/> that describes the	event. 
      The feed provider determines the feeds that the event should be 
      distributed to, and determines which Subscribers need to be notified.</t>
      <t> 
      How Feeds are defined and the process by which events are identified for 
      subscribers is out-of-scope of this	specification.
			</t>

			<t>
			When a SET is available for a subscriber, the Feed Provider
			attempts to deliver the SET based on the Subscriber's registered
			delivery mechanism:
			<list style="symbols">
				<t>The subscriber provided a web-callback endpoint, the
				publisher uses an HTTP/1.1 POST to the endpoint to deliver the
				event to the registered subscriber;
			  </t>

			  <t>Or, the Feed Provider delivers the event through a different
        method not defined by this specification.
			  </t>
			</list>
			</t>

			<t>After a SET is delivered to all subscribers, Feed Providers
				do not typically maintain SETs or histories. As such,
				published SETs SHOULD be self-validating (e.g. signed).
			</t>

			<t>
				If delivery to any particular subscriber has been delayed for
				an extended period of time, the Feed Provider MAY suspend the
				subscription and even stop maintaining outstanding SETs for
				the Subscriber at its discretion and available resources. See subscription
				<spanx style="verb">state</spanx> in <xref target="subscribeMetadata" />.
			</t>

			<t>
				Upon receiving a SET, the Subscriber reads the token and validates 
        it. Based on the content of the token, the subscriber decides what 
        if any action it needs to take in response to the SET. For 
        example, in response to a SCIM event <xref target="idevent-scim"/> 
        indicating a changed resource, the subscriber might perform a 
        SCIM GET request (see <xref target="RFC7644">Section 3.4</xref>)
				to the affected resource URI in order to confidentially obtain 
        the current state of the affected SCIM resource. 
      </t>
        
      <t>
        The action a Subscriber takes in response to a SET MAY be substantially 
        different than merely copying the action of the publisher. A single 
        SET MAY trigger multiple receiver actions. For example, upon receiving 
        notification that a user resource has been added to a group, the 
        Subscriber may first determine that the user does not exist in the 
        Subscriber's domain. The Subscriber translates the event into two 
        actions:<list style="numbers">
          <t>Retrieve the user (e.g. using SCIM GET) and then provisions 
          the user locally. After enabling the user,</t>
          <t>The Subscriber then enables the user for the application 
        associated with membership in the Feed Publisher's group.</t>
        </list>  
			</t>
		</section>

		

		<section title="Event Feeds">
			<t>
	      An Feed is defined by a <spanx style="verb">feedUri</spanx>. The 
        Feed provides a stream of SETs to be delivered to registered 
        Subscribers based on a Subscription. An individual Subscription contains the 
        metadata about a particular Subscriber regarding their subscription 
        to a particular <spanx style="verb">feedUri</spanx>. Subscription
        metadata indicates the current subscription state indicating whether 
        all events are delivered, pending, or whether delivery has failed. 
        Subscription metadata also describes the method of event delivery, 
        and any associated security and configuration information (see
				<xref target="subscribeMetadata" />
				).
			</t>

      <section anchor="feedtypes" title="Feed Types">
          <t>
            A Feed Provider MAY define Feeds based on a number of
            criteria. This specification does not specify or limit the basis for
            which a service provider defines the resources or entities 
            contained in a Feed or how feed URIs should be
            specified. Some possible methods for defining entities covered by
            a Feed include:
            <list style="hanging">
              <t hangText="By Resource or Subject"><vspace blankLines="0"/>A
                resource or subject might have its own associated event
                notification Feed. For example, a User's mobile application may
                require notification of changes or rights defined in a SCIM User
                resource associated with the mobile user.
              </t>

              <t hangText="By Endpoint"><vspace blankLines="0"/>A Feed might 
                be defined by an endpoint where any event relating to a 
                resource within an endpoint is
                delivered to a subscriber. This type of feed is likely to have
                many notifications as the number of resources in an endpoint 
                grows (e.g. a SCIM "/Users") and SHOULD be used with caution. 
                Typically only privileged partners would be allowed to use
                this type of feed. For example, an enterprise wishes to be 
                notified of all change events to any of its users assuming all 
                users within the endpoint are related to the subscribing 
                enterprise.
              </t>

              <t hangText="By Filter"><vspace blankLines="0"/>A Feed might 
                define a collection of
                resources based on a filter that describes a set of matching
                criteria a resource may be included in a Feed. Note that 
                this type of Feed may require extra processing by the Feed 
                Provider to determine if any particular SET event matches 
                the filter criteria. It may also be difficult for the Feed
                Provider to notify Subscribers of additions and deletions
                of resources to the Feed as the resources in the Feed MAY change
                based on the filter itself.
              </t>

              <t hangText="By Group"><vspace blankLines="0"/>All entities
                or resources within some specified group. For example, 
                all resources within a SCIM Group could be used to define 
                the resources for which SETs will be issued within a particular 
                Feed. 
              </t>
            </list>

            The list above is intended to show common use cases for defining
            Feeds. How Feeds are defined is out-of-scope of this
            specification. 
          </t>

        </section>
				
				<section anchor="feedMetadata" title="Feed Metadata">
					
					<t>
						Feed metadata consists of the following singular
						attributes:
						<list style="hanging">
							<t hangText="feedName">
								<vspace />
								A required string value
								containing a name for the feed. May be used in administrative
								user interfaces to assist subscribers in Feed selection. The
								value MUST be unique within a given administrative domain. This is a
								REQUIRED attribute.
							</t>

							<t hangText="feedUri">
								<vspace />
								An attribute of type
								<spanx style="verb">String</spanx>
								that is a
								unique URI identifying the feed. This attribute characteristic
								<spanx style="verb">mutability</spanx>
								is
								<spanx style="verb">immutable</spanx>
								and SHALL NOT change once assigned. The value of this 
                attribute MAY be the SCIM URI for the Feed resource (e.g. 
                <spanx style="verb">https://scim.example.com/Feeds/88bc00de</spanx>).
                This is a REQUIRED attribute. 
							</t>

							<t hangText="description">
								<vspace />
								A
								<spanx style="verb">String</spanx>
								attribute that describes the purpose of the feed in human
								readable form. This is an OPTIONAL attribute.
							</t>

              <t hangText="events"><vspace/>An attribute whose value 
              is a JSON object consisting of multi-valued JSON 
              attributes where each attribute is the name of a primary 
              event URI and each value represents an event extension to 
              the primary event. An empty array SHALL indicate there are 
              no extensions. When set, Feeds SHALL only provide the primary
              events defined. However, a Feed Provider MAY provide additional
              extensions that are not declared. This is an OPTIONAL attribute.
              <vspace blankLines="1"/>The following is a non-normative 
              example events claim:
              <figure anchor="exEvents" title="Example Events Attribute">
              <artwork>"events":{
  "urn:ietf:params:scim:event:passwordReset":[
      "https://example.com/scim/event/passwordResetExt"],
  "https://specs.openid.net/logout":[]
}</artwork>
              <postamble></postamble>
              </figure>
              In the above example, the feed has two events 
              defined. The first is a hypothetical password reset, and the second is
              a hypothetical OpenID Connect logout. The password reset event
              has one extension defined which is 
              <spanx style="verb">https://example.com/scim/event/passwordResetExt</spanx>.</t>
              
							<t hangText="type">
								<vspace />
								An OPTIONAL String attribute that MAY have values such as:
								<list style="hanging">
									<t hangText="resource">
										Indicates that the Feed is for
										events related to a specific resource. In such cases,
										the value of the attribute
										<spanx style="verb">filter</spanx>
										is set to a specific
										resource URI or
										<spanx style="verb">/Me</spanx>
										.
									</t>
									<t hangText="endpoint">
										Indicates that the Feed is for all
										events that occur for resources within a specific endpoint.
										In such cases,
										<spanx style="verb">filter</spanx>
										is set to
										an endpoint container for a group of resources (e.g.
										<spanx style="verb">/Users</spanx>
										).
									</t>
									<t hangText="filter">
										Indicates that events for a Feed
										will be selected based on events relating to the set of
										resources described by a filter. For example, the value of the attribute
										<spanx style="verb">filter</spanx>
										is a SCIM filter <xref target="RFC7644">Section 3.4.2</xref> that
										describes a condition that selects a set of resources that
										match before or after a resource state change.
									</t>
									<t hangText="group">
										Indicates that events for a Feed
										will be based on events relating to the set of resources
										listed in a group such as a SCIM Group<xref target="RFC7643">Section 4.2</xref>. 
									</t>
									
								</list>
                The attribute is typically used by the Feed Publisher to 
                determine the meaning and content of the Feed <spanx style="verb">filter</spanx>
                attribute.
							</t>

              <!-- Should we leave this to profiling specifications? -->
							<t hangText="filter">
								<vspace />
								An OPTIONAL String value containing a filter whose syntax is defined by 
                a profiling specification (e.g. SCIM) or the Feed Publisher. 
                For example in SCIM, a filter MAY be 
                a filter <xref target="RFC7644">Section 3.4.2.2</xref>),
								a resource, or a SCIM endpoint URI depending on the value
                of <spanx style="verb">type</spanx>. And, if the SCIM 
                Feed type is <spanx style="verb">resource</spanx>,
                than the filter value is a URI for a SCIM resource.
							</t>

						</list>
					</t>

					<t>
						The following multi-valued attributes are defined:
						<list style="hanging">
							<t hangText="deliveryModes"><vspace/>
                One or more URIs representing the methods of
								delivery supported by the Feed Publisher. Values in this
                attribute correspond to the Subscription <spanx style="verb">methodUri</spanx>
                attribute (see <xref target="subscribeMetadata"/>).
							</t>

						</list>
					</t>
      </section>  
      <section anchor="feedMgmt" title="SCIM Feed Management">
        
        <t>When Feeds are managed within a SCIM service provider <xref target="RFC7644"/>,
        Feed resources use schema defined in <xref target="feedMetadata"/>
        and use a schema value of <spanx style="verb">urn:ietf:params:scim:schemas:event:2.0:Feed</spanx>.
        The SCIM <spanx style="verb">ResourceType</spanx> definition defines 
        the location of the SCIM service provider endpoint for <spanx style="verb">Feed</spanx>
        resources. </t>
        
        <t>
        The Feed <spanx style="verb">ResourceType</spanx> definition 
        is typically defined as follows:
        <figure anchor="feedType" title="SCIM Feed ResourceType Definition">
<artwork>{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
  "id": "Feed",
  "name": "Feed",
  "endpoint": "/Feeds",
  "description": "Event Feeds",
  "schema": "urn:ietf:params:scim:schemas:event:2.0:Feed",
  "schemaExtensions": []
}</artwork>
        </figure>
        </t>
        <t>To retrieve information about a <spanx style="verb">Feed</spanx> 
        or a number of feeds, subscribers or management clients MAY query 
        the <spanx style="verb">/Feeds</spanx> endpoint as defined in 
        <xref target="RFC7644">Section 3.4</xref>.</t>
        
        <t><figure anchor="feedGetRequest" title="Example Feed GET Request">
         <preamble>The example below retrieves a specific Feed resource whose 
         <spanx style="verb">id</spanx> is <spanx style="verb">548b7c3f77c8bab33a4fef40</spanx>.</preamble>
<artwork>GET /Feeds/88bc00de776d49d5b535ede882d98f74
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8</artwork>
         </figure></t>
         <figure anchor="feedGetResponse" title="Example Feed GET Response">
         <preamble>The response below shows an example Feed resource
         that describes an available feed.</preamble>
<artwork>HTTP/1.1 200 OK
Content-Type: application/scim+json
Location: 
 https://example.com/v2/Feeds/88bc00de776d49d5b535ede882d98f74
ETag: 9d1c124149f522472e7a511c85b3a31b

{
  "schemas":["urn:ietf:params:scim:schemas:event:2.0:Feed"],
  "id":"88bc00de776d49d5b535ede882d98f74",
  "feedName":"OIDCLogoutFeed",
  "feedUri":"https://oidc.example.com/",
  "description":"Logout events from oidc.example.com",
  "type":"resource",
  "events":[
    "https://specs.openid.net/logout":[]
  ]
  "meta":{
     ... SCIM meta attributes ...
  }
}</artwork>
        </figure>
        <t>In the above example (<xref target="feedGetResponse"/>) we can
        observe that the Feed has only one event type, 
        <spanx style="verb">https://specs.openid.net/logout</spanx> and
        has no extensions defined for the event (see empty square brackets).
        Note also, that no value for <spanx style="verb">filter</spanx> has been specified
        suggesting that the Feed will return events about all subjects of
        the publisher.</t>
      </section>
	</section>	
  <section title="Subscriptions">
   
      <t>A subscription represents an agreement to deliver SETs from a
      specified Feed URI from a Feed Provider to an individual Subscriber
      entity also known as the "audience". The method of delivery and the 
      parameters for delivery are specified a set of parameters called 
      subscription metadata (see <xref target="subscribeMetadata"/>).
      </t>   
    
    <section anchor="subscribeMetadata" title="Subscription Metadata">
          <t>
            A subscription is defined by the following metadata:
            <list style="hanging">
              <t hangText="feedUri"><vspace />A String value containing the URI
              for a feed supported by the feed provider. It describes the 
              content of the feed and MAY also be a resolvable URI where the
              feed meta data may be returned as a JSON object. REQUIRED.</t>

              <t hangText="methodUri"><vspace />A REQUIRED single-valued string
              which is a URI with a prefix of <spanx style="verb">urn:ietf:params:set:method</spanx>.
              This specification defines HTTP POST delivery <xref target="delivery"/>:
              <spanx style="verb">urn:ietf:params:set:method:HTTP:webCallback</spanx>
              <vspace blankLines="0"/> in which the Feed Provider delivers events 
              using HTTP POST to a specified callback URI.</t>
              
              <t hangText="deliveryUri"><vspace/>A URI that describes the location 
              SETs are delivered. Its format and usage requirements are 
              defined by the associated <spanx style="verb">methodUri</spanx> 
              specification.</t>

              <t hangText="aud"><vspace blankLines="0"/>An OPTIONAL URI representing 
              the audience of the subscription. The value SHALL be the value 
              of "aud" when the subscriber receives SETs from the feed.
              </t>

              <t hangText="feedJwk"><vspace blankLines="0"/>An OPTIONAL public JSON Web Key (see
              <xref target="RFC7517" />) that will be used
              to sign published SETs. If present, the Subscriber can
              authenticate SETs relayed from the Feed Provider.</t>

              <t hangText="confidentialJwk"><vspace blankLines="0"/>An OPTIONAL Subscriber 
              provided public JSON Web Key (see <xref target="RFC7517" />) 
              that MAY be used by the Feed Provider to encrypt SET tokens 
              for the specified Subscriber.</t>

              <t hangText="subStatus"><vspace blankLines="0"/>An OPTIONAL 
              value that indicates the current status of a Subscription:<list>
                  <t><spanx style="verb">on</spanx> - indicates the Subscription
                  has been verified and that the Feed Provider MAY pass 
                  SETs to the Subscriber.</t>

                  <t><spanx style="verb">verify</spanx> - indicates the 
                  Subscription is pending verification. While in "verify", 
                  published SETs SHALL NOT be stored or delivered to the 
                  Subscriber. Once verified, the status returns to 
                  <spanx style="verb">on</spanx>.</t>

                  <t><spanx style="verb">paused</spanx> - indicates the
                  Feed Provider is temporarily suspending delivery to
                  Subscriber. While <spanx style="verb">paused</spanx>,
                  SETs SHOULD be retained and delivered when state
                  returns to <spanx style="verb">on</spanx>. Verification
                  is NOT required when returning to <spanx style="verb">on</spanx>.</t>

                  <t><spanx style="verb">off</spanx> - indicates that the
                  Subscription is no longer passing SETs. While in off mode,
                  the subscription metadata is maintained, but new events 
                  are ignored, not delivered or retained. Before returning
                  to <spanx style="verb">on</spanx>, a verification MUST
                  be performed.</t>

                  <t><spanx style="verb">fail</spanx> - indicates that the
                  feed provider was unable to deliver SETs to the
                  Subscriber for an extended period of time, or due to a call
                  failure to the registered web call back URI. Unlike paused
                  status, a failed subscription no longer receives SETs,
                  nor are they retained by the Feed Provider. Before returning
                  to <spanx style="verb">on</spanx>, a verification MUST
                  be performed.</t>
                </list></t>
                
              <t hangText="maxRetries"><vspace blankLines="0"/>An OPTIONAL number indicating the 
              maximum number of attempts to deliver a SET. A value of '0'
              indicates there is no maximum. Upon reaching the maximum, the 
              Subscription <spanx style="verb">subStatus</spanx> attribute is set
              to <spanx style="verb">failed</spanx>.</t>
              
              <t hangText="maxDeliveryTime"><vspace blankLines="0"/>An OPTIONAL number indicating
              the maximum amount of time in seconds a SET MAY take for
              successful delivery.  Upon reaching the maximum, the 
              subscription <spanx style="verb">subStatus</spanx> is set
              to <spanx style="verb">failed</spanx>. If undefined, there is no maximum time.</t>
              
              <t hangText="minDeliveryInterval"><vspace blankLines="0"/>An OPTIONAL
              integer that represents the minimum interval in seconds between deliveries. A value of '0'
              indicates delivery should happen immediately. When delivery is
              a polling method (e.g. HTTP GET), it is the expected time between subscriber attempts.
              When in push mode (e.g. HTTP POST), it is the interval the server
              will wait before sending a new event or events.</t>
            </list></t>
        </section>
        
        <section anchor="subState" title="Subscription State Model">
          <t>The Subscription attribute <spanx style="verb">subStatus</spanx>
          tracks the state of any particular subscription with regards to
          whether SETs are ready or able to be delivered. The impact on 
          delivery processing is described in <xref target="processingStatus"/>.</t>
          <figure anchor="stateDiag" title="Subscription States at Feed Publisher">
          <preamble>The following is the state machine representation of a
          subscription on a Feed Publisher. Note that a subscription cannot
          be made active until a verification process has been completed. As 
          such, a newly created subscription begins with state 
          <spanx style="verb">verify</spanx>.</preamble>
          <artwork>
                               +
                               |
                             Create
                               v
    +------+              +----------+
    | fail +->Restart---->|  verify  |
    +------+              +----+-----+
        ^                      |
        |&lt;----Confirm Fail&lt;----+
        |                   Confirm
        |                      v
        |                 +----------+               +--------+
        |                 |          +--->Suspend--->|        |
        +------Timeout&lt;---+    on    |               | paused |
                          |          |&lt;--Resume&lt;-----+        |
                          +-+--------+               +--------+
                            |      ^
                         Disable Enable
                            v      |
                          +--------+-+
                          |   off    |
                          +----------+</artwork>
          </figure>
          <t>In the above diagram, the following actions impact the state
          of a Subscription. <spanx style="verb">subStatus</spanx> values are shown in
          the boxes, and change based on the following actions:<list style="hanging">
          
            <t hangText="Create"><vspace/>A Subscriber or an administrator creates
            a new subscription using SCIM as described in <xref target="createSub"></xref>.
            The initial state is <spanx style="verb">verify</spanx>.</t>
            
            <t hangText="Confirm"><vspace/>The Feed Publisher sends a verification
            SET to the Subscriber which confirms with the correct response as
            described in <xref target="verifySubscription"/>. If it succeeds
            to deliver, the Feed Publisher mail retry or set state to 
            <spanx style="verb">on</spanx>.</t>
            
            <t hangText="Confirm Fail"><vspace/>If the confirmation fails,
            the Feed Publisher sets the state to <spanx style="verb">fail</spanx>
            requiring administrative action to correct the issue and 
            <spanx style="verb">Restart</spanx>.</t>
            
            <t hangText="Timeout"><vspace/>A Feed Publisher having not being
            able to deliver a SET over one or more retries which has reached
            a limit of attempts (<spanx style="verb">maxRetries</spanx>) 
            or time (<spanx style="verb">maxDeliveryTime</spanx>)
            MAY set the subscription state to <spanx style="verb">fail</spanx>.
            In general, the intention is to indicate the maximum
            number of retries or time a Feed Publisher is able to wait until
            SET event loss begins to occur resulting in the failed state.</t>
            
            <t hangText="Restart"><vspace/>An administrator having corrected the 
            failed delivery condition modifies the Subscription state to
            <spanx style="verb">verify</spanx> (e.g. see <xref target="patchSub"/>).
            </t>
            
            <t hangText="Suspend and Resume"><vspace/>A Subscription MAY be 
            suspended and resumed by updating the Subscription state to
            <spanx style="verb">paused</spanx> or <spanx style="verb">on</spanx>. For
            example, see see <xref target="patchSub"/>. While suspended,
            the Feed Publisher MAY retain undelivered SETs for a period of time.
            If the Feed Publisher is no longer able to retain SETs, the subscription
            state SHOULD be set to <spanx style="verb">off</spanx> to indicate
            SETs are being lost.
            </t>
            
            <t hangText="Enable and Disable"><vspace/>A subscription MAY be
            disabled and enabled by updating the Subscription state to
            <spanx style="verb">off</spanx> or <spanx style="verb">on</spanx>. For
            example, see see <xref target="patchSub"/>. While the Subscription
            is disabled, all SETs that occur at the Feed Publisher are lost.</t>
          </list></t>
        
        </section>
        <section anchor="subscribeMgmt" title="SCIM Subscription Management">
          <t>A Feed Publisher MAY use SCIM to support management of subscriptions.
          Typically this involves support for the Subscription Resource Type, 
          and the corresponding SCIM operations to create, update, retrieve
          Subscription Resources. For SCIM service provider capability and 
          schema discovery, see <xref target="RFC7644">Section 4</xref>.</t>
          <section title="SCIM Subscription Resource Type">
            <t>When Subscriptions are managed within a SCIM service provider 
            <xref target="RFC7644"/>, Subscription resources use schema 
            defined in <xref target="subscribeMetadata"/> and use a schema 
            value of 
            <spanx style="verb">urn:ietf:params:scim:schemas:event:2.0:Subscription</spanx>.</t>
        
            <t>The SCIM Subscription <spanx style="verb">ResourceType</spanx> definition 
            is defined as follows:<figure anchor="subscriptionType" title="SCIM Subscription ResourceType Definition">
<artwork>{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
  "id": "Subscription",
  "name": "Subscription",
  "endpoint": "/Subscriptions",
  "description": "Subscribers to SET Feeds",
  "schema": "urn:ietf:params:scim:schemas:event:2.0:Subscription",
  "schemaExtensions": []
}</artwork>
            </figure>
            </t>
            <t>To retrieve information about one or more Subscriptions, 
            Subscribers or management clients MAY query the <spanx style="verb">/Subscriptions</spanx> endpoint 
            as defined in <xref target="RFC7644">Section 3.4</xref>.</t>
        
            <t><figure anchor="subscriptionGetRequest" title="Example SCIM Subscription GET Request">
            <preamble>The example below retrieves a specific <spanx style="verb">Subscription</spanx> resource whose 
            <spanx style="verb">id</spanx> is <spanx style="verb">548b7c3f77c8bab33a4fef40</spanx>.</preamble>
            <artwork>GET /Subscriptions/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8</artwork>
            </figure></t>
            <t><figure anchor="subscriptionResponse" title="Example Subscription GET Response">
            <preamble>The response below shows an example Feed resource
            that describes an available feed.</preamble>
            <artwork>HTTP/1.1 200 OK
Content-Type: application/scim+json
Location: 
 https://example.com/v2/Subscriptions/767aad7853d240debc8e3c962051c1c0

{
  "schemas":["urn:ietf:params:scim:schemas:event:2.0:Subscription"],
  "id":"767aad7853d240debc8e3c962051c1c0",
  "feedName":"OIDCLogoutFeed",
  "feedUri":
    "https://example.com/v2/Feeds/88bc00de776d49d5b535ede882d98f74",
  "methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
  "deliveryUri":"https://notify.examplerp.com/Events",
  "aud":"https://sets.myexamplerp.com",
  "subStatus":"pending",
  "maxDeliveryTime":3600,
  "minDeliveryInterval":0,
  "description":"Logout events from oidc.example.com",
  "meta":{
     ... SCIM meta attributes ...
  }
}</artwork>
            </figure></t>
            <t>In the above example (<xref target="subscriptionResponse"/>)
            observe that the subscription is for the SCIM <spanx style="verb">Feed</spanx> resource defined at 
            <spanx style="verb">https://example.com/v2/Feeds/88bc00de776d49d5b535ede882d98f74</spanx>.
            The current subscription state is <spanx style="verb">pending</spanx>
            which suggest the Subscription Verification (see <xref target="verifySubscription"/>) process has not yet 
            completed. Since there is no value for <spanx style="verb">feedJwk</spanx>, )
            or <spanx style="verb">confidentialJwk</spanx>, the SETs will be
            sent without signing or encryption (plain text).</t>          
          </section>
          <section anchor="createSub" title="New Subscription Requests">
            <t>To subscribe to a feed, the subscriber of management client
            uses the SCIM Create operation as defined in <xref target="RFC7644">Section 3.3</xref>.
            SCIM subscription management service providers MAY have additional 
            schema requirements which MAY be discovered using SCIM service 
            configuration and schema discovery, see <xref target="RFC7644">Section 4</xref>.
            </t>
            <figure anchor="createSubscription" title="Example New Subscription Request in SCIM">
            <preamble>In the following non-normative example, a new Subscription resource
            is requested. Note that the SCIM service provider automatically
            assigns the <spanx style="verb">id</spanx> attribute.</preamble>
 <artwork>POST /Subscriptions
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8

{
  "schemas":["urn:ietf:params:scim:schemas:event:2.0:Subscription"],
  "feedName":"OIDCLogoutFeed",
  "feedUri":
    "https://example.com/v2/Feeds/88bc00de776d49d5b535ede882d98f74",
  "methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
  "deliveryUri":"https://notify.examplerp.com/Events",
  "aud":"https://sets.myexamplerp.com",
  "maxDeliveryTime":3600,
  "minDeliveryInterval":0,
  "description":"Logout events from oidc.example.com"
}</artwork>

            </figure>
            <figure anchor="createSubscriptionResponse" title="Example Response to Subscription Request">
            <preamble>In following non-normative response, the SCIM service provider
            has automatically assigned a resource location as well as an
            <spanx style="verb">id</spanx>. Usually upon creation, the
            initial value of <spanx style="verb">subStatus</spanx> is 
            <spanx style="verb">pending</spanx> indicating that the 
            Subscription Verification (see <xref target="verifySubscription"/>) 
            has not been completed.</preamble>
<artwork>HTTP/1.1 201 Created
Content-Type: application/scim+json
Location: 
 https://example.com/v2/Subscriptions/767aad7853d240debc8e3c962051c1c0

{
  "schemas":["urn:ietf:params:scim:schemas:event:2.0:Subscription"],
  "id":"767aad7853d240debc8e3c962051c1c0",
  "feedName":"OIDCLogoutFeed",
  "feedUri":
    "https://example.com/v2/Feeds/88bc00de776d49d5b535ede882d98f74",
  "methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
  "deliveryUri":"https://notify.examplerp.com/Events",
  "aud":"https://sets.myexamplerp.com",
  "subStatus":"pending",
  "maxDeliveryTime":3600,
  "minDeliveryInterval":0,
  "description":"Logout events from oidc.example.com",
  "meta":{
     ... SCIM meta attributes ...
  }
}</artwork>
            </figure>
          </section>
          <section anchor="patchSub" title="Updating Subscriptions">
            <t>To modify a Subscription, a Subscriber or authorized management
            client MAY use the SCIM PUT operation (see <xref target="RFC7644">Section 3.5.1</xref>) 
            and MAY use the SCIM PATCH operation (see <xref target="RFC7644">Section 3.5.2</xref>) 
            if supported by the SCIM Subscription server. </t>
            
            <figure anchor="subscriptionPatch" title="Example SCIM Subscription Update">
            <preamble>In the following non-normative example, the client
            is requesting that <spanx style="verb">subStatus</spanx> be 
            changed to <spanx style="verb">paused</spanx> for the Subscription
            whose path is identified by the request URI path.</preamble>
<artwork>PATCH /Subscriptions/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8

{
  "schemas":
    ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op":"replace",
    "path":"subStatus",
    "value":"paused"
  }]
}

</artwork>
            </figure>
            
         
          </section>
        </section>
        <section anchor="verifySubscription" title="Subscription Verification">
          <t>In order to avoid ongoing communication issues and to minimize
          requirements for Feed Providers to maintain a series of SETs indefinitely,
          a verification process is used to confirm that the requested 
          Subscription distribution endpoints are valid and that SETs may be
          successfully delivered. When a Subscription is created or modified,
          or goes into a failed or off state, 
          the Feed Provider SHALL set the Subscription state attribute 
          <spanx style="verb">subStatus</spanx> to <spanx style="verb">verify</spanx> 
          and send a Verify SET message to the subscriber. If the SET is
          delivered successfully, the subscription state SHOULD be turned to 
          <spanx style="verb">on</spanx>. If however verification fails due
          to a timeout or connection failure, or any other cause, the 
          Subscription status SHALL be set to <spanx style="verb">fail</spanx>.
          </t>
          
          <section anchor="verifyPush" title="Verifying Subscriptions">
            <t>The verification process 
            serves to verify that the identified Subscriber is willing to receive
            SETs and is correctly configured. In the case of push style
            subscriptions, where the publisher initiates the action to deliver
            a SET, Verification can also serve to prevent
            a Feed Publication server from flooding an endpoint which did not 
            actually request a Subscription.</t>
            
            <t>
            A Feed Provider MAY send a Verify SET at any time in order to 
            reverify connectivity and to assure the subscriber the subscription
            is valid (e.g. as a keep alive technique).</t>

            <t>To confirm a subscription, the Feed Provider SHALL send a
            verification SET to the subscriber using the registered 
            <spanx style="verb">methodUri</spanx> mechanism. The Verify 
            SET contains the following attributes:<list style="hanging">
              <t hangText="events">Set with a value of 
              <spanx style="verb">[[this RFC URL]]#verify</spanx>.</t>

              <t hangText="iss">Set to the URI of the feed publisher (see 
              <xref target="I-D.hunt-idevent-token"/>).</t>

              <t hangText="aud">MUST be set to a value that matches the
              subscription <spanx style="verb">feedUri</spanx> requested.</t>

              <t hangText="exp">A value that indicates the
              time the verification request will expire. Once expired, the
              server will set the subscription state to <spanx style="verb">fail</spanx>.</t>
              
            </list>
            
            In the SET payload area, a specific delivery method MAY include
            an attribute that can be used to confirm the subscriber has 
            successfully received and parsed the SET (e.g. such as the 
            inclusion of a challenge attribute, see <xref target="CallbackVerify"/>).
            
            If a confidential JWK was supplied, then the SET SHOULD
            be encrypted with the provided key. Successful parsing of the
            message confirms that provides confirmation of correct 
            configuration and possession of keys.</t>
            
            <t>Note that the verification event URI 
            (<spanx style="verb">[[this RFC URL]]#verify</spanx>) 
            type is not normally listed as part of the definition of a 
            Feed as it is not part of the normal information flow of a Feed.
            Any Feed MAY include a SET verification event whether listed or
            not in the Feed event metadata.</t>

            <t>
            Upon receiving the SET, the subscriber acknowledges receipt as 
            defined by the method profile (for example, see <xref target="CallbackVerify"/>).</t>
            
            <t>
            If the subscriber is unable to parse the verification SET, fails 
            to return the correct challenge, or the SET is not delivered after
            a period of time. The Feed Publisher will set <spanx style="verb">subStatus</spanx>
            to <spanx style="verb">failed</spanx>. </t>
          
          </section>
          
        </section>
  </section>
    
  <section anchor="delivery" title="Event Delivery">
     <section anchor="deliveryDefinition" title="Introduction to Event Delivery Methods">
        <t>Each event delivery method SHOULD have the following information:<list style="hanging">
          <t hangText="Description"><vspace/>The <spanx style="verb">methodUri</spanx> URI value
          for the delivery method and a description of the method.</t>
          <t hangText="Subscription Verification Procedure"><vspace/>The procedure
          that the configuration for a subscription is confirmed causing the
          subscription status to be set to <spanx style="verb">on</spanx>.</t>
          <t hangText="Delivery Message Format"><vspace/>A description of an event delivery
          message and how to locate the event token(s) as well as any additional
          error signalling.</t>
          <t hangText="Delivery Procedure"><vspace/>The protocol procedure for a delivery
          request (push or poll), and the expected successful response.</t>
          <t hangText="Failure Conditions"><vspace/>A description of the failure
          conditions that might occur and the impact on the subscriptions
          operational status (<spanx style="verb">subStatus</spanx>) if any.</t>
          
        </list> </t>
        <t>This specification defines the first delivery method known as 
        "HTTP Web Callback Method" which uses HTTP POST.</t>
     </section> 
     <section title="Delivery Processing">
     <t>As mentioned in <xref target="subscribeMetadata"/>, the attribute 
     <spanx style="verb">subStatus</spanx> defines the current state of 
     a subscribers subscription. <xref target="stateDiag"/> shows a state 
     diagram for Subscriptions. The following describes that actions taken
     by the Feed Publisher based upon <spanx style="verb">subStatus</spanx>.</t>
     <texttable anchor="processingStatus" title="Delivery Processing By Status">
     <ttcol>Status</ttcol><ttcol>Action</ttcol>
     
     <c>on</c><c>Delivery SHALL be attempted based on the method defined
     in the subscription attribute <spanx style="verb">methodUri</spanx>.
     If the SET fails to deliver it MAY be retained for a retry delivery in a minimum
     of <spanx style="verb">minDeliveryInterval</spanx> seconds. If new SETs arrive before 
     the interval, the SETs MUST be held for delivery in order of reception.
     If this is a repeat attempt to deliver, the Feed Publisher MAY discard
     the SET if <spanx style="verb">maxRetries</spanx> or <spanx style="verb">maxDeliveryTime</spanx> 
     is exceeded. If a SET is discarded, the Feed Publisher MAY set <spanx style="verb">subStatus</spanx>
     to <spanx style="verb">failed</spanx>.</c>
     
     <c>verify</c><c>If the SET is not a
     Verify SET, the SET MAY be retained for a retry at the Feed Publishers discretion. 
     If a Verify SET fails to deliver, the Feed Publisher SHALL set <spanx style="verb">subStatus</spanx>
     to <spanx style="verb">failed</spanx>. The Feed Publish MAY opt to make
     multiple attempts to complete a verification during which status remains as 
     <spanx style="verb">verify</spanx>.</c>
     
     <c>paused</c><c>The SET is held for delivery in a queue. The Feed Publisher MAY
     at its own discretion set the subscription state to <spanx style="verb">failed</spanx>
     if <spanx style="verb">subStatus</spanx> is not returned to <spanx style="verb">on</spanx>
     in what the Feed Publisher determines to be a reasonable amount of time.</c>
     
     <c>off</c><c>The SET is ignored.</c>
     
     <c>fail</c><c>The SET is ignored due to a previous unrecoverable error. </c>
     
     </texttable>
     </section>
     <section anchor="httpPost" title="HTTP Web Callback Method">
        
       <section title="Description">
            <t>This method allows a feed provider to use HTTP POST 
            (<xref target="RFC7231">Section 4.3.3</xref>) to deliver
            SETs to a registered web callback URI. The Subscription 
            <spanx style="verb">methodUri</spanx> value for this method 
            is <spanx style="verb">urn:ietf:params:set:method:HTTP:webCallback</spanx>.</t>
            
            <t>This delivery method is capable of delivering a single SET per
            HTTP POST request. Depending on the settings for the 
            subscription metadata (see <xref target="subscribeMetadata"/>), 
            the SET MAY be signed and/or encrypted as defined in <xref target="I-D.hunt-idevent-token"/>.</t>
            
            <t>The Subscription's <spanx style="verb">deliveryUri</spanx> 
            attribute indicates the location of a Subscriber provided 
            endpoint which can accept HTTP POST requests (e.g. 
            <spanx style="verb">https://notify.examplerp.com/Events</spanx>).</t>
       </section>
          
       <section anchor="httpMessageFormat" title="Delivery Message Format">
            <t>The content-type for this method is <spanx style="verb">application/jwt</spanx>
            and consists of a single SET token (see <xref target="I-D.hunt-idevent-token"/>).</t>
            <figure anchor="messageSet" title="Example Web Callback POST Message">
              <artwork>
  eyJhbGciOiJub25lIn0
  .
  eyJwdWJsaXNoZXJVcmkiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20iLCJmZWV
  kVXJpcyI6WyJodHRwczovL2podWIuZXhhbXBsZS5jb20vRmVlZHMvOThkNTI0Nj
  FmYTViYmM4Nzk1OTNiNzc1NCIsImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZ
  WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6
  WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ
  hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG
  VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX
  SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk
  b2VAZXhhbXBsZS5jb20ifV0sInBhc3N3b3JkIjoibm90NHUybm8iLCJ1c2VyTmF
  tZSI6Impkb2UiLCJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJuYW
  1lIjp7ImdpdmVuTmFtZSI6IkpvaG4iLCJmYW1pbHlOYW1lIjoiRG9lIn19fQ
  .
</artwork>
            </figure>
            
          </section>

          <section anchor="CallbackVerify" title="Subscription Verification">
            
            <t>This profile specifies the verification method for HTTP POST 
            and is based on the general verification method described in
            <xref target="verifyPush"/>.</t>

            <t>To confirm a subscription, the Feed Provider SHALL send a
            verification SET to the subscriber using the registered 
            <spanx style="verb">methodUri</spanx> mechanism which in this case
            is <spanx style="verb">urn:ietf:params:set:method:HTTP:webCallback</spanx>. 
            The Verify SET contains the attributes listed in <xref target="verifyPush"/>.</t>
              
            <t>A payload attribute <spanx style="verb">confirmChallenge</spanx>
            is provided with a String value that the subscriber SHALL echo 
            back in its response. The intent is to confirm that the Subscriber 
            has successfully parsed the SET and is not just echoing back 
            HTTP success.</t>

            <figure anchor="verifyPostEvent" title="Example Verification SET with Challenge">
            <preamble>A non-normative JSON representation of an event to be
            sent to a subscriber as a subscription confirmation. Note the
            event is not yet encoded as a JWT token:</preamble>
<artwork>{  
  "jti": "4d3559ec67504aaba65d40b0363faad8",
  "events":["[[this RFC URL]]#verify"],
  "iat": 1458496404,
  "iss": "https://scim.example.com",  
  "exp": 1458497000,
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754",
   "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7"
  ], 
  "[[this RFC URL]]#verify":{
    "confirmChallenge":"ca2179f4-8936-479a-a76d-5486e2baacd7"
  }  
}</artwork>
            </figure>
            
            <t>The above SET is encoded as a JWT and transmitted to the 
            Subscriber as shown in <xref target="postSet"/>.</t>

            <t>Upon receiving a subscription verify SET, a confirming
            subscriber SHALL respond with a JSON object that includes a 
            <spanx style="verb">challengeResponse</spanx> attribute and 
            the value that was provided in <spanx style="verb">confirmChallenge</spanx>.
            The content type header is set to <spanx style="verb">application/json</spanx>.</t>
            
            <figure anchor="verifyPostResponse" title="Example Response to Verify SET with Challenge">
              <preamble>
The following is a non-normative example response to a Verify SET 
received via HTTP/1.1 POST and includes a JSON object containing the 
confirmation attribute and value.</preamble>
<artwork>HTTP/1.1 200 OK
Content-Type: application/json

{  
  "challengeResponse":"ca2179f4-8936-479a-a76d-5486e2baacd7"
}</artwork>
            </figure>

            <t>
            If the subscriber returns a non-matching value or an HTTP status
            other than a 200 series response, the subscription 
            <spanx style="verb">state</spanx> SHALL be set to <spanx style="verb">fail</spanx>.
            A declining subscriber MAY simply respond with any 400 series HTTP
            error (e.g. 404).</t>
          
          </section>

          <section title="Delivery Procedure">
            <t>To deliver an event, the publisher generates an event delivery message
            and uses HTTP POST to the registered endpoint. The content-type of the
            message is <spanx style="verb">application/jwt</spanx> and the expected
            response type (accept) is <spanx style="verb">application/json</spanx>.</t>
            
            <figure align="left" anchor="postSet" title="Example Web Callback POST Request">
              <artwork align="left">POST /Events  HTTP/1.1

Host: notify.examplerp.com
Accept: application/json
Content-Type: application/jwt
"eyJhbGciOiJub25lIn0
.
eyJwdWJsaXNoZXJVcmkiOiJodHRwczovL3NjaW0uZXhhbXBsZS5jb20iLCJmZWV
kVXJpcyI6WyJodHRwczovL2podWIuZXhhbXBsZS5jb20vRmVlZHMvOThkNTI0Nj
FmYTViYmM4Nzk1OTNiNzc1NCIsImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZ
WVkcy81ZDc2MDQ1MTZiMWQwODY0MWQ3Njc2ZWU3Il0sInJlc291cmNlVXJpcyI6
WyJodHRwczovL3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZ
hYjYxZTc1MjFkOSJdLCJldmVudFR5cGVzIjpbIkNSRUFURSJdLCJhdHRyaWJ1dG
VzIjpbImlkIiwibmFtZSIsInVzZXJOYW1lIiwicGFzc3dvcmQiLCJlbWFpbHMiX
SwidmFsdWVzIjp7ImVtYWlscyI6W3sidHlwZSI6IndvcmsiLCJ2YWx1ZSI6Impk
b2VAZXhhbXBsZS5jb20ifV0sInBhc3N3b3JkIjoibm90NHUybm8iLCJ1c2VyTmF
tZSI6Impkb2UiLCJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkiLCJuYW
1lIjp7ImdpdmVuTmFtZSI6IkpvaG4iLCJmYW1pbHlOYW1lIjoiRG9lIn19fQ
.</artwork>
            </figure>
            <t>Upon receipt of the request, the Subscriber SHALL validate the 
            JWT structure of the SET as defined in <xref target="RFC7519">Section 7.2</xref>.
            The Subscriber SHALL also validate the SET information as described
            in <xref target="I-D.hunt-idevent-token">Section 2</xref>.</t>
            <t>If the SET is determined to be valid, the Subscriber SHALL
            indicate successful submission by responding with HTTP Status
            202 as <spanx style="verb">Accepted</spanx> (see <xref target="RFC7231">Section 6.3.3</xref>).</t>
            
            <t>If SET or JWT is invalid, or there is an HTTP error, the Subscriber
            SHALL respond with the appropriate HTTP error or an HTTP Status
            400 Bad Request error as follows:</t>
            <texttable anchor="reqErrors" title="HTTP Status 400 Errors">
              <ttcol>Err Value</ttcol><ttcol>Description</ttcol>
              <c>jwtParse</c><c>Invalid or unparsable JWT or JSON structure.</c>
              <c>jwtHdr</c><c>In invalid JWT header was detected.</c>
              <c>jwtCypto</c><c>Unable to parse due to unsupported algorithm.</c>
              <c>jws</c><c>Signature was not validated.</c>
              <c>jwe</c><c>Unable to decrypt JWE encoded data.</c>
              <c>jwtAud</c><c>Invalid audience value.</c>
              <c>jwtIss</c><c>Issuer not recognized.</c>
              <c>setType</c><c>An unexpected event type was received.</c>
              <c>setParse</c><c>Invalid structure was encountered such as inability
              to parse SET event payload.</c>
              <c>setData</c><c>SET event claims incomplete or invalid.</c>
              <c>dup</c><c>A duplicate SET was received and has been ignored.</c>
            </texttable>
            
            <figure anchor="goodPostResponse" title="Example Successful Delivery Response">
            <preamble>The following is a non-normative example of a successful
            receipt of a SET.</preamble>
              <artwork>HTTP/1.1 202 Accepted</artwork>
            </figure> 
            
            <t>An HTTP Status 400 Bad Request response includes a JSON
            object which provides details about the error. The JSON object
            includes the JSON attributes: <list style="hanging">
              <t hangText="err"><vspace/>A value which is a keyword that 
              describes the error (see <xref target="reqErrors"/>).</t>
              <t hangText="description"><vspace/>A human-readable text that provides
              additional diagnostic information.</t>
            </list> </t>
            <figure anchor="badPostResponse" title="Example Bad Request Response">
            <preamble>The following is an example non-normative Bad
            Request error.</preamble>
            <artwork>HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "err":"dup",
  "description":"SET already received. Ignored."

}</artwork>
            </figure>

          
            
            <t></t>
       </section>

      
     </section>
  </section>

  <section anchor="Security" title="Security Considerations" toc="default">

      <t>[TO BE COMPLETED]</t>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <section anchor="notifyMechRegistry"
               title="Event Notification Mechanism Registry">
        <t>[TODO: Registration for Notification Mechanisms]</t>
      </section>
      
      <section title="SCIM Schema Registration">
        <t>As per the "SCIM Schema URIs for Data Resources" registry established
        by <xref target="RFC7643">Section 10.3</xref>, the following defines and registers
        the following SCIM URIs and Resource Types for Feeds and Subscriptions.</t>
        <texttable>
        <ttcol>Schema URI</ttcol><ttcol>Name</ttcol><ttcol>ResourceType</ttcol><ttcol>Reference</ttcol>
        
        <c>urn:ietf:params:scim: schemas:event:2.0: Feed</c>
        <c>SET Event Feed</c>
        <c>Feed</c>
        <c><xref target="feedMgmt"/></c>
        
        <c>urn:ietf:params:scim: schemas:event:2.0: Subscription</c>
        <c>SET Event Subscription</c>
        <c>Subscription</c>
        <c><xref target="subscribeMgmt"/></c>
        
        </texttable>
      
      </section>

  
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml' ?>
      
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml' ?><!-- HTTP Semantics -->
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7519.xml' ?><!-- JWT -->
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7644.xml' ?><!-- SCIM API -->
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7643.xml' ?><!-- SCIM Schema -->

      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hunt-idevent-token-05.xml'?>

    </references>

    <references title="Informative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7515.xml' ?><!-- JWS -->
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7516.xml' ?><!-- JWE -->
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7517.xml' ?><!-- JWK -->
      

      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-webpush-protocol-02.xml'?>
 
      <reference anchor="idevent-scim">
        
        <front>
          <title>SCIM Event Extensions (work in progress)</title>
          <author fullname="Phil Hunt"><organization>Oracle Corporation</organization></author>
          <date/>
        </front>  
        <format type="TXT" target="draft-hunt-idevent-scim-00.txt"/>    
      </reference>

     <!-- 
      <reference anchor="Order-Operations">
        <front>
          <title>Order of Operations: Programming Languages</title>

          <author>
            <organization>Wikipedia</organization>
          </author>

          <date/>
        </front>

        <format target="http://en.wikipedia.org/wiki/Order_of_operations#Programming_languages"
                type="HTML"/>
      </reference>
       -->
    </references>

    <section title="Contributors"/>

    <section title="Acknowledgments">
      <t>The editor would like to thank the participants in the the SCIM
      working group for their support of this specification.</t>
    </section>

    <section title="Change Log">
      <t>Draft 00 - PH - First Draft</t>
      <t>Draft 01 - PH - <list style="symbols">
        <t>Removed the version from filename in GITHUB version</t>
        <t>Aligned document with new SET terminology from I-D.hunt-idevent-token</t>
        <t>Simplified draft to only define HTTP POST profile (TBD)</t>
        <t>Removed webpush and polling modes (can be re-added later).</t>
        <t>Added SCIM management definitions for Feeds</t>
        <t>Added delivery information including errors</t>
        <t>Added subscription management information (e.g. how to subscribe)</t>
        <t>Updated reference to idevent-token to published IETF version</t>
        <t>Added a state diagram for Subscriptions</t>
      </list> </t>
    </section>
  </back>
</rfc>