-
Notifications
You must be signed in to change notification settings - Fork 4
/
draft-hunt-idevent-distribution.xml
1338 lines (1171 loc) · 63.2 KB
/
draft-hunt-idevent-distribution.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?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 | |
| <------------------------+ |
| SCIM | | SET |
| Feed |Subscription Request | Feed |
| Mgmt <------------------------+ Subscriber |
| | | |
| |Subscription Mgmt | |
| <------------------------+ |
| | | |
+------------+ | |
+------------+ | |
| | | |
| 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 |
+------+ +----+-----+
^ |
|<----Confirm Fail<----+
| Confirm
| v
| +----------+ +--------+
| | +--->Suspend--->| |
+------Timeout<---+ on | | paused |
| |<--Resume<-----+ |
+-+--------+ +--------+
| ^
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