forked from independentid/Identity-Events
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-hunt-secevent-stream-mgmt.xml
2150 lines (1924 loc) · 92.6 KB
/
draft-hunt-secevent-stream-mgmt.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-secevent-stream-mgmt-00"
ipr="trust200902">
<front>
<title abbrev="draft-hunt-secevent-stream-mgmt">
SET Security Event Stream Management and Provisioning</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>
<date year="2017" />
<keyword>Internet-Draft</keyword>
<abstract>
<t>
This specification defines a "control plane" service which
enables a client (e.g. an Event Receiver) to establish,
monitor, and manage a Security Event Token
Stream.
</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction and Overview" toc="default">
<t>
This specification defines a "Control Plane" service that defines
how an Event Receiver or its agent may provision, monitor, and manage
the configuration of an Event Stream that delivers Security Event Tokens
(see <xref target="I-D.ietf-secevent-token"/>) using delivery
methods such as specified in the SET Delivery Using HTTP
Specification (see <xref target="I-D.ietf-secevent-delivery"/>).
</t>
<t>
The specification defines the common metadata Event Transmitters
and Receivers use to describe HTTP service endpoints, methods, optional
signing and encryption modes, as well as the type and content of SETs
delivered over a Stream. The specification defines how
the Event Receiver parties may review and update the current
configuration and confirm operational delivery status using HTTP over TLS.
</t>
<t>The mandatory part of this specification (see <xref target="monitorStream"/>)
uses a profile of SCIM (see <xref target="RFC7643"/> and
<xref target="RFC7644"/>) to implement Event Stream configuration, monitoring
and retrieval using HTTP GET <xref target="RFC7231">Section 4.3.1</xref>.
Additionally, SCIM MAY be used to manage and update Event Stream
configuration and operational state.</t>
<t>The choice os SCIM has been recommended as it is intended as
a general purpose layer that can be applied to many underlying systems.
SCIM's extensibility mechanisms to define data types (resource types)
enable it to be flexibly used by specifications intenting to profile
SET Tokens and Delivery for use in many ways.</t>
<t>For the purposes of the Control Plane, SCIM <xref target="RFC7643">Section 2</xref>
provides the JSON data definitions that enable the Control Plane to allow
service providers and clients to negotiate attributes and
resource types used in different SET Profiles. This includes
declarations and discovery of attribute types, mutability,
cardinality, and returnability that MAY differ between deployments
and SET Event type profiles. For HTTP protocol handling and error
signaling, the processing rules in <xref target="RFC7644"/> SHALL be applied. </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>. Many examples
show only partial response and may use <spanx style="verb">...</spanx>
to indicate omitted data.
</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.ietf-secevent-token"/>
and SET Token Delivery specification <xref target="I-D.ietf-secevent-delivery"/>.</t>
<t>
The following definitions are defined for Security Event distribution:
<list style="hanging">
<t hangText="Control Plane"><vspace/>
A Control Plane represents an service offered by an Event
Transmitter that lets an Event Receiver query the current
operational and/or error status of an Event Stream. The
Control Plane MAY also be used to retrieve Event Stream
and SET configuration data.
</t>
<t hangText="Data Plane"><vspace/>
The Data Plane represents the HTTP service offered by an
Event Receiver that allows the Event Transmitter to
deliver multiple SETs via HTTP POST as part of an Event
Stream.</t>
<t hangText="Client">A Client is any actor, typically
represented by an authorization credential, authorized to
make changes to an Event Stream. Verify often this is
an actor belonging to the Event Receiver organization. Actors
can be servers, monitoring services, and administrators.</t>
</list></t>
</section>
</section>
<section anchor="monitorStream" title="Stream Monitoring and Configuration Retrieval">
<t>The Control Plane is an HTTP service associated with an Event
Transmitter that enables the provisioning and monitoring of Event
Streams by entities such Event Receivers, administrators, and
monitoring services. This section describes required functionality
to enable Event Receivers to retrieve configuration attributes and
to detect SET delivery problems that may occur when an Event
Transmitter fails to deliver SETs.</t>
<t>This specification also defines optional Control Plane services
to create and update streams in sections <xref target="streamManagement"/>
and <xref target="manageSubjects"/>.</t>
<section anchor="subscribeMetadata" title="Event Stream Configuration Attributes">
<t>
An Event Stream is defined by a set of attributes which together
define an Event Stream's operational configuration:
<list style="hanging">
<t hangText="eventUris"><vspace />A read only array of JSON
String values which are the URIs of events configured for the
Event Stream. This attribute is assigned by the Control Plane
provider in response to receiving an Event Stream creation or
update request. See <spanx style="verb">eventUris_req</spanx>.</t>
<t hangText="eventUris_req"><vspace/>An array of JSON String values
which are the URIs of events requested by the Event Receiver for
the Stream. This attribute is modifiable. An Event Stream
provider MAY use this attribute to request requested Event URIs
over time that may not be initially offered.</t>
<t hangText="eventUris_avail"><vspace/>A read only array of
JSON String values which are the URIs of events that the Event
Transmitter is able to support. This attribute MAY be used by
Control Plane clients to discover new events that may become
available over time.</t>
<!-- Not really needed
<t hangText="feedUri"><vspace />A JSON 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 JSON String value
which represents the method used to transfer SETs to the Event
Receiver. See <xref target="I-D.ietf-secevent-delivery"/>.</t>
<t hangText="deliveryUri"><vspace />A JSON String value
containing a URI that describes the location where
SETs are received (e.g. via HTTP POST). Its format and usage requirements are
defined by the associated <spanx style="verb">methodUri</spanx>.</t>
<t hangText="iss"><vspace />The URI for the publisher of the SETs
that will be issued for the Event Stream. See
<xref target="I-D.ietf-secevent-token">Section 2.1</xref>.</t>
<t hangText="aud"><vspace blankLines="0" />An OPTIONAL
JSON Array of JSON String values which are URIs representing
the audience(s) of the Event Stream. The value SHALL be the value
of SET "aud" claim sent to the Event Receiver.
</t>
<t hangText="iss_jwksUri"><vspace blankLines="0" />An OPTIONAL
String that contains the URL of the SET issuers public JSON
Web Key Set <xref target="RFC7517"></xref>. This contains
the signing key(s) the Event Receiver uses to validate SET
signatures from the Event Transmitter that will be used by the
Event Receiver to verify the authenticity of issued SETs. </t>
<t hangText="aud_jwksUri"><vspace blankLines="0" />An OPTIONAL
JSON Web Key Set <xref target="RFC7517" /> that contains the
Event Receiver's encryption keys that MAY be used by the
Event Transmitter to
encrypt SET tokens for the specified Event Receiver.</t>
<t hangText="status"><vspace blankLines="0" />An OPTIONAL
JSON String keyword that indicates the current state of an Event Stream.
More information on the Event Stream state can be found in
<xref target="subState" />. Valid keywords are:<list>
<t><spanx style="verb">on</spanx> - indicates the Event Stream
has been verified and that the Feed Provider MAY pass
SETs to the Event Receiver.</t>
<!-- No longer used with client initiated verify
<t><spanx style="verb">verify</spanx> - indicates the
Event Stream is pending verification. While in "verify",
SETs, except for the verify SET (see
<xref target="verifyStream"/>) are not delivered to the
Event Receiver. Once verified, the status returns to
<spanx style="verb">on</spanx>.</t>
-->
<t><spanx style="verb">paused</spanx> - indicates the
Event Stream is temporarily suspended. While
<spanx style="verb">paused</spanx>, SETs SHOULD be
retained and delivered when state returns to
<spanx style="verb">on</spanx>. If delivery is paused
for an extended period defined by the Event Transmitter,
the Event Transmitter MAY change the state to
<spanx style="verb">off</spanx> indicating SETs are
no longer retained.</t>
<t><spanx style="verb">off</spanx> - indicates that the
Event Stream is no longer passing SETs. While in off mode,
the Event Stream configuration 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
Event Stream was unable to deliver SETs to the
Event Receiver due an unrecoverable error or for an
extended period of time. Unlike paused
status, a failed Event Stream does not retain existing
or new SETs that are issued. Before returning
to <spanx style="verb">on</spanx>, a verification MUST
be performed.</t>
</list></t>
<t hangText="maxRetries"><vspace blankLines="0" />An OPTIONAL
JSON 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
Event Stream <spanx style="verb">status</spanx> attribute is set
to <spanx style="verb">failed</spanx>.</t>
<t hangText="maxDeliveryTime"><vspace />
An OPTIONAL number indicating
the maximum amount of time in seconds a SET MAY take for
successful delivery per request or cumulatively across
multiple retries. Upon reaching the maximum, the
Event Stream <spanx style="verb">status</spanx> is set
to <spanx style="verb">failed</spanx>. If undefined, there
is no maximum time.</t>
<t hangText="minDeliveryInterval"><vspace />
An OPTIONAL JSON 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 Event Receiver 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>
<t hangText="txErr"><vspace />
An OPTIONAL JSON String keyword value.
When the Event Stream has <spanx style="verb">subState</spanx>
set to <spanx style="verb">fail</spanx>, one of the following
error keywords is set:<list>
<t><spanx style="verb">connection</spanx> indicates an
error occurred attempting to open a TCP connection with
the assigned endpoint.</t>
<t><spanx style="verb">tls</spanx> indicates an error
occurred establishing a TLS connection with the assigned
endpoint.</t>
<t><spanx style="verb">dnsname</spanx> indicates an error
occurred establishing a TLS connection where the dnsname
was not validated.</t>
<t><spanx style="verb">receiver</spanx> indicates an error
occurred whereby the Event Receiver has indicated an error
for which the Event Transmitter is unable to correct.</t>
</list>
</t>
<t hangText="txErrDesc"><vspace />
An OPTIONAL String value that is
usually human readable that provides further diagnostic
detail by the indicated <spanx style="verb">txErr</spanx>
error code.</t>
<t hangText="verifyNonce">A String value that when changed
or set by a Control Plane client will cause the Event Transmitter
to issue a single Verify Event based on the nonce value provided (see
<xref target="verifyStream"/>). The intent of the value is to
allow the Event Receiver to confirm the Verify Event received
matches the value set in the configuration. While this value MAY
be updated (see <xref target="verifyStream"/>), its value is
usually not returned as part of an Event Stream configuration. </t>
<t hangText="subjects"><vspace />
An OPTIONAL complex attribute containing sub objects whose
sub-attributes define subjects against which SETs may be issued.
The following sub-attributes are defined:<list style="hanging">
<t hangText="value">A String which uniquely identifies a
subject (or set of subjects) to be included in the Stream.
The format and type of value is defined by the 'type'
sub-attribute.</t>
<t hangText="iss">A String which contains the URI of the
issuer of the subject identified in the
<spanx style="verb">value</spanx> attribute. When not supplied
the issuer is assumed to be the Event Stream issuer.
</t>
<t hangText="type">A case-insensitive canonical String value
which defines the contents of the attribute 'value'. Valid
type values are:<list style="hanging">
<t hangText="OIDC">Is a String value corresponding to an OpenID
Connect subject. The corresponding <spanx style="verb">iss</spanx>
attribute is set with the OpenId Connect iss value. </t>
<t hangText="SAML">A String value that is a URI that
represents the subject of a SAML Identity Provider.</t>
<t hangText="EMAIL">A String Value that is the Email
addresses for a subject. The value SHOULD be specified
according to <xref target="RFC5321" />.</t>
<t hangText="PHIONE">Phone numbers for the user. The value
SHOULD be specified according to the format defined in
<xref target="RFC3966" />, e.g., 'tel:+1-201-555-0123'.</t>
<t hangText="User">A SCIM User where value is the 'id' of a
User resource in the local SCIM service provider.</t>
<t hangText="Group">A SCIM Group where the value is the 'id'
of a Group resource in the local SCIM service provider.</t>
<t hangText="URI">A miscellaneous subject that can be
identified by a URI.</t>
</list></t>
</list></t>
</list></t>
<t>Additional Event Stream configuration (attributes) MAY be defined
as extensions. The method for adding new attributes is defined in
<xref target="RFC7643">Section 3.3</xref>.</t>
</section>
<section anchor="getStatus" title="Checking Stream Configuration and Stream State">
<t>An Event Receiver MAY check the current status of a Stream
the Event Transmitter's Control Plane service by performing an
HTTP GET using the provided URI from the Event Transmitter either
through an administrative process or via the optional Stream
creation response defined in <xref target="createSub"/>.</t>
<t>The format of the Stream GET request and response is defined
by <xref target="RFC7644">Section 3.4</xref>.
</t>
<t>In addition to the basic attributes defined in
<xref target="RFC7643">Section 2</xref> common to all resource
types, an <spanx style="verb">EventStream</spanx> resource types
uses the attributes defined in <xref target="subscribeMetadata" />.
As with any SCIM resource, an <spanx style="verb">EventStream</spanx>
resource MUST include the JSON attributes <spanx style="verb">schemas</spanx>
and <spanx style="verb">id</spanx> as defined in <xref target="RFC7643"/>:
<list style="hanging">
<t hangText="schemas"><vspace/>Is an array of Strings with at
least a single value of
<spanx style="verb">urn:ietf:params:scim:schemas:event:2.0:EventStream</spanx>.
Configuration MAY be extented through the addition of other schema
URI values such as in the case where a new delivery method or
SET profile needs to define additional attributes.</t>
<t hangText="id"><vspace/>Is a String which is a permanent unique
identifier for <spanx style="verb">EventStream</spanx> resources.
The value which is also used to define a permanent Event Stream
Resource URI.</t>
</list>
</t>
<figure anchor="getRequest" title="Example EventStream HTTP GET Request">
<preamble>The example below retrieves a specific <spanx style="verb">EventStream</spanx> resource whose
<spanx style="verb">id</spanx> is <spanx style="verb">548b7c3f77c8bab33a4fef40</spanx>.</preamble>
<artwork>GET /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8</artwork>
</figure>
<figure anchor="streamResponse" title="Example Stream GET Response">
<preamble>Below is an example response to the
<spanx style="verb">EventStream</spanx> retrieval
made in <xref target="getRequest"/>.</preamble>
<artwork>HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/EventStreams/767aad7853d240debc8e3c962051c1c0
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"fail",
"txErr":"connection",
"txErrDesc":"TCP connect error to notify.examplerp.com.",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}</artwork>
</figure>
<t>In the above figure, the <spanx style="verb">EventStream</spanx>
shows a <spanx style="verb">status</spanx> of <spanx style="verb">fail</spanx>
due to a TCP connection error. In this case, the Event Receiver is
able to discover that its endpoint was unavailable and has been
marked failed by the Event Transmitter (possibly explaining a lack
of received SETs). Typically, with this
type of error, appropriate operations staff would be alerted and some
corrective action would be taken to check for a configuration
error or service failure.</t>
<t>The frequency with which Event Receivers poll the
Event Stream status depends on factors such as:
<list style="symbols">
<t>The level of technical fault tolerance and availability of the
receiving endpoint.</t>
<t>The amount of risk that can be tolerated for lost
events. For example, if Security Events are considered informational,
then infrequent (hourly or daily) may be sufficient.</t>
<t>The amount of buffer recovery offered by an Event Transmitter
which MAY be minutes depending on SET frequency and buffer size.</t>
</list>
In many cases Event Stream status monitoring may be triggered on a
timeout basis. Event Receivers would typically poll if they have not
received a SET for some period during which SETs would be expected
based on past experience.
</t>
<t>Receivers MAY use the endpoint
<spanx style="verb">/EventStreams</spanx> to query and retrieve available
Event Streams based on the provided <spanx style="verb">Authorization</spanx>
header.
</t>
<figure anchor="getCommonRequest" title="Example Stream HTTP GET Request From Common Endpoint">
<preamble>The example below retrieves any <spanx style="verb">EventStream</spanx>
resources based solely on the requestor's authorization header.
</preamble>
<artwork>GET /EventStreams/
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8</artwork>
</figure>
<figure anchor="getListResponse" title="Example Event Stream List/Query Response Form">
<artwork>HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/EventStreams/767aad7853d240debc8e3c962051c1c0
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":1,
"itemsPerPage":10,
"startIndex":1,
"Resources":[
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris_avail":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"fail",
"txErr":"connection",
"txErrDesc":"TCP connect error to notify.examplerp.com.",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}]
}</artwork>
</figure>
</section>
<section anchor="subState" title="Event Stream State Model">
<t>The Event Stream configuration attribute <spanx style="verb">status</spanx>
reports the current state of an Event Stream with regards to
whether the stream is operational or is in a suspended or failed state.
Additionally, the <spanx style="verb">status</spanx> attribute
can be used to pause or stop streams using the stream configuration
update functions described in <xref target="streamManagement"/>.</t>
<figure anchor="stateDiag" title="Event Stream States at Event Transmitter">
<preamble>The following is the state machine representation of a
Event Stream on a Event Transmitter. Note that a Event Stream cannot
be made active until a verification process has been completed. As
such, a newly created Event Stream begins with state
<spanx style="verb">on</spanx>.</preamble>
<artwork align="center"> +
Create
|
+--------+ +------v-----+ +--------+
| +-Restart-> +--Suspend-> |
| fail | | on | | paused |
| <--Error--+ <--Resume--+ |
+--------+ +-+-------^--+ +---+----+
| | |
Disable Enable |
| | |
+-v-------+--+ |
| off <--Limited-----+
+------------+</artwork>
</figure>
<t>In <xref target="stateDiag"/>, the following actions impact the
operational state of an Event Stream. <spanx style="verb">status</spanx>
values are shown in the boxes, and change based on the following
actions:<list style="hanging">
<t hangText="Create"><vspace />A Event Receiver or an administrator creates
a new Event Stream as described in <xref target="createSub"></xref>.
The initial state is <spanx style="verb">on</spanx>.</t>
<!-- No used now that receiver verifies success
<t hangText="Confirm Fail"><vspace />If the confirmation fails,
the Event Transmitter 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="Error"><vspace />An Event Transmitter that has not been
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 Event Stream state to <spanx style="verb">fail</spanx>.
What stream status is set to <spanx style="verb">failed</spanx>,
the Event Transmitter is indicating that SETs are being lost
and may not be recoverable.</t>
<t hangText="Limited"><vspace/>A paused Event Stream has reached
the transmitters ability to retain SETs for delivery. The Event
Transmitter changes the state to <spanx style="verb">off</spanx>
indicating SET loss is potentially occurring.</t>
<t hangText="Restart"><vspace />An administrator having corrected the
failed delivery condition modifies the Event Stream state to
<spanx style="verb">on</spanx> (e.g. see <xref target="patchSub" />).
</t>
<t hangText="Suspend and Resume"><vspace />An Event Stream MAY be
suspended and resumed by updating the Event Stream state to
<spanx style="verb">paused</spanx> or <spanx style="verb">on</spanx>. For
example, see see <xref target="patchSub" />. While suspended,
the Event Transmitter retains undelivered SETs for a period of time
and resources specified by the Event Transmitter (see
<spanx style="verb">Limited</spanx>).</t>
<t hangText="Enable and Disable"><vspace />A Event Stream MAY be
disabled and enabled by updating the Event Stream <spanx style="verb">state</spanx> to
<spanx style="verb">off</spanx> or <spanx style="verb">on</spanx>. For
example, see see <xref target="patchSub" />. While the Event Stream
is disabled, all SETs that occur at the Event Transmitter are lost.</t>
</list></t>
</section>
</section>
<section anchor="streamManagement" title="Stream Management and Provisioning">
<t>This section describes optional Stream management provisioning
features that allow receivers or provisioning systems to create
streams and update configuration to perform actions such as
rotation, and operational state (e.g. suspend, stop, or resume)
management.</t>
<t>The operations specified in this section are based on <xref target="RFC7644"/>.
SCIM schema declarations for the <spanx style="verb">EventStream</spanx>
resources are defined in
<xref target="eventResourceType"/>. HTTP Protocol usage and
processing rules are provided by <xref target="RFC7644"/>.</t>
<section anchor="createSub" title="Creating An Event Stream">
<t>To define an Event Stream, the Event Receiver or its administrator
(known as the client) first obtains an authorization credential
allowing the ability to define a new Stream. Note: the process
for registering to obtain credentials and permission to register
is out-of-scope of this specification.</t>
<t>Upon obtaining authorization, the client issues an HTTP POST
request as defined in <xref target="RFC7644">Section 3.3</xref>.
To complete the request, the administrative entity provides the
required Stream configuration attributes as specified
in <xref target="subscribeMetadata"/>, the delivery method
<xref target="I-D.ietf-secevent-delivery"/> and any additional
configuration specified by the SET Event Specifications that are
being used.</t>
<t>The client MAY discover the Event Transmitter's
Control Plane service for the schema requirements for
<spanx style="verb">EventStream</spanx> resource type and any
other extensions using SCIM schema discovery in
<xref target="RFC7644">Section 4</xref>.
</t>
<t>The process to create an Event Stream is as follows:<list style="numbers">
<t>The client initiates an HTTP POST to the Control Plane
endpoint and provides a
JSON document defining an EventStream which contains information
about the Event Receivers endpoints, settings, and keys.</t>
<t>Upon validating the request, the Event Transmitters control
plane provisions the stream and updates the EventStream configuration
with the corresponding Event Transmitter information.</t>
<t>The Control Plane responds to the request from step 1 and
returns the final representation of the Event Stream configuration
along with a pointer to the created EventStream resource that
the client MAY use to monitor status and update configuration.</t>
<t>Upon receiving the response, the client completes the
client side configuration and provisioning based upon the
returned EventStream configuration.</t>
</list></t>
<figure anchor="createSubscription" title="Example Create Event Stream Request">
<preamble>In the following non-normative example, a request to
create a new <spanx style="verb">EventStream</spanx> is
submitted.</preamble>
<artwork>POST /EventStreams
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"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 Create EventStream Request">
<preamble>In following non-normative response, the Control
Plane provider has automatically assigned an HTTP addressable
location for the EventStream resource as well as an
<spanx style="verb">id</spanx>. Additionally, the Control Plane
response below includes additional configuration data for
<spanx style="verb">iss</spanx> and
<spanx style="verb">iss_jwksUri</spanx>.</preamble>
<artwork>HTTP/1.1 201 Created
Content-Type: application/scim+json
Location:
https://example.com/v2/EventStreams/767aad7853d240debc8e3c962051c1c0
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris_avail":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"on",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"iss":"oidc.example.com"
"iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks"
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}</artwork>
</figure>
</section>
<section anchor="patchSub" title="Updating An Event Stream">
<t>Two HTTP methods are available to update an Event Stream
configuration. <list>
<t>The HTTP PUT operation accepts a JSON Document
representing an existing EventStream configuration and replaces
it.</t>
<t>An optional HTTP PATCH operation uses a JSON Patch
<xref target="RFC6902"/> style request format to allow manipulation
of specific EventStream configuration such as
(but not limited to) <spanx style="verb">status</spanx>, and
<spanx style="verb">subjects</spanx>.</t>
</list></t>
<section title="Update using HTTP PUT">
<t>The HTTP PUT method allows a client having previously
received the EventStream JSON document to modify the document
and replace the Control Plane provider's copy. In using this
method, the client is not required to remove data normally
asserted or defined by the Event Stream Control Plane provider
(e.g. attributes that are read only).
The processing rules of <xref target="RFC7644"/> enable the
client to "put back" what was previously received allowing
the Control Plane provider to figure out what attributes
need updating and which attributes are ignored. For example,
while "id" is immutable, the Control Plane provider will simply
ignore attempts to replace its value. When processing is complete
the final accepted state is represented in the HTTP Response.</t>
<figure anchor="putSubscription" title="Example Replace Event Stream Request">
<preamble>In the following non-normative example, a request to
replace the existing EventStream <spanx style="verb">EventStream</spanx> is
submitted. In this example, the change shown is the status
is now set to <spanx style="verb">off</spanx>. Note that the client
does not have to remove read-only attributes such as <spanx style="verb">eventUris</spanx>
and <spanx style="verb">eventUris_avail</spanx> as these values
are ignored as per <xref target="RFC7644">Section 3.5.1</xref>.</preamble>
<artwork>PUT /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris_avail":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"off",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"iss":"oidc.example.com"
"iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks"
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}</artwork>
</figure>
<figure anchor="putSubscriptionResponse" title="Example Response to PUT EventStream Request">
<preamble>In following non-normative response, the Control
Plane provider responds with the processed final state
of the submitted EventStream.</preamble>
<artwork>HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/v2/EventStreams/767aad7853d240debc8e3c962051c1c0
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris_avail":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"off",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"iss":"oidc.example.com"
"iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks"
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}</artwork>
</figure>
</section>
<section anchor="updatePatch" title="Update using HTTP PATCH">
<t>Periodically, Event Receiver parties MAY have need to update an
EventStream configuration for the purpose of:<list style="symbols">
<t>Rotating access credentials or keys</t>
<t>Updating endpoint configuration</t>
<t>Making operational changes such as pausing, resetting, or
disabling an Event Stream.</t>
<t>Other operations (e.g. such as adding or removing subjects)
as defined by profiling Event specifications.</t>
</list></t>
<t>As documented in <xref target="RFC7644">Section 3.5.2</xref>,
one or more PATCH operations (which are based on
<xref target="RFC6902"/>) can be made against a single
EventStream resource. The update is expressed as a JSON document.
The JSON document contains an attribute <spanx style="verb">Operations</spanx>
which contains an array of JSON objects each of which each have the
following attributes:<list style="hanging">
<t hangText="op"><vspace/>A JSON attribute whose value is one of
<spanx style="verb">add</spanx>, <spanx style="verb">remove</spanx>,
or <spanx style="verb">replace</spanx>.</t>
<t hangText="path"><vspace/>A JSON attribute whose value is a document
attribute path (see <xref target="RFC7644">Section 3.5.2</xref>)
describing the attribute or sub-attribute or
value to be updated in the case of multi-valued complex attributes
such as <spanx style="verb">subjects</spanx>.</t>
<t hangText="value"><vspace/>The value to be assigned to the JSON
document attribute defined in <spanx style="verb">path</spanx>.</t>
</list></t>
<figure anchor="subscriptionPatch" title="Example EventStream PATCH Request">
<preamble>In the following non-normative example, the client
requests that the <spanx style="verb">status</spanx> configuration
attribute be changed to <spanx style="verb">paused</spanx> for
the EventStream whose path is identified by the request URI path.</preamble>
<artwork>PATCH /EventStreams/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":"status",
"value":"paused"
}]
}</artwork>
</figure>
<t>In the above figure, upon receiving the request, the Event
Transmitter would stop sending Events to the Receiver based on
the requested value of <spanx style="verb">status</spanx> being
set to <spanx style="verb">paused</spanx>.</t>
<t>
<figure anchor="memberPatch" title="Example Changing the Members of EventStream">
<preamble>In the following non-normative example, the client
requests the addition and removal of two subjects
from an existing EventStream. This operation is discussed
further in <xref target="subjMgmtStream"/>.</preamble>
<artwork>PATCH /EventStreams/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":"add",
"path":"subjects",
"value":{
"type":"EMAIL",
"value":"alice@example.com"
}
},
{
"op":remove",
"path":"subjects[value eq \"bob@example.com\"]
}]
}</artwork>
</figure>
In the above request, the second operation, the remove operation,
uses a <spanx style="verb">path</spanx> attribute to specify a
matching filter the correct array element of <spanx style="verb">subjects</spanx>
by matching the appropriate sub-attributes which are denoted by
square brackets (see <xref target="RFC7644">Figure 1 and 2</xref>
for other examples and ABNF for filters).
In this case the composite filter of the <spanx style="verb">subjects</spanx> sub-attributes
<spanx style="verb">type</spanx> and <spanx style="verb">value</spanx>
are used to remove the correct JSON array element.
Upon receiving the request, the EventStream subjects attribute would be
updated to reflect the changes.
</t>
</section>
</section>
</section>
<section anchor="manageSubjects" title="Models for Managing Stream Subjects">
<t>The extensibility of SCIM enables many ways to model
subjects that are part of an Event Stream. This section
explores a few alternatives that profiling specifications could
use to manage the contents of an Event Stream. These examples
include managing subjects:<list style="symbols">
<t>As an attribute of an Event Stream configuration (see <xref target="subjMgmtStream"/>);</t>
<t>As a member of SCIM Group (see <xref target="subjMgmtGroup"/>); and,</t>
<t>As a specific Subject resource (see <xref target="subjMgmtResource"/>).</t>
</list>
</t>
<section anchor="subjectConsiderations" title="General Considerations for Managing Subjects">
<t>As a privacy and scalability consideration, profiling specifications SHOULD
consider that most deployments SHOULD not allow the subjects that
are part of an Event Stream to be enumerated in a single request.
For example, in <xref target="subjMgmtStream"/>,
the Event Stream configuration attribute <spanx style="verb">subjects</spanx>
is typically not returned when querying Event Stream configurations
(see <xref target="getStatus" />). This is because the number of
values may be too large (e.g. great than 100k values or even
in the billions or more). Further, depending on the Security
Event types being exchanged, Event Receivers MAY confirm that a
subject is part of a stream for privacy reasons. </t>
<t>The ability to return attributes such as <spanx style="verb">subjects</spanx>
is indicated by Control Plane service providers in schema discovery
(see <xref target="RFC7644">Section 4</xref>) as the schema attribute
<spanx style="verb">returned</spanx>. For <spanx style="verb">subjects</spanx>
this attribute SHOULD be set to <spanx style="verb">request</spanx> or
<spanx style="verb">never</spanx>. In <spanx style="verb">request</spanx> mode,
the client must specifically request the attribute <spanx style="verb">subjects</spanx>
to have it enumerated. If the mode is <spanx style="emph">never</spanx>,
the attribute SHALL NOT be returned to clients. In all cases however,
a client MAY execute a query to verify the presence of a subject:</t>
</section>
<section anchor="subjMgmtStream" title="Subjects as Part of Stream Configuration">
<t>In this section, examples are given using the
<spanx style="verb">subjects</spanx> attribute of Event Stream
configuration described in <xref target="subscribeMetadata"/></t>
<t>The following sections assume subject membership within streams
is defined by the <spanx style="verb">subjects</spanx> attribute of