idnits 2.17.1 draft-hunt-secevent-stream-mgmt-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 14 characters in excess of 72. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: 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 Section 4.2, the Event Stream configuration attribute "subjects" is typically not returned when querying Event Stream configurations (see Section 2.2). 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. -- The document date (October 29, 2017) is 2372 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC5988' is defined on line 1682, but no explicit reference was found in the text == Unused Reference: 'RFC7519' is defined on line 1695, but no explicit reference was found in the text == Unused Reference: 'RFC7515' is defined on line 1721, but no explicit reference was found in the text == Unused Reference: 'RFC7516' is defined on line 1725, but no explicit reference was found in the text == Outdated reference: A later version (-02) exists of draft-ietf-secevent-delivery-00 == Outdated reference: A later version (-13) exists of draft-ietf-secevent-token-02 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track October 29, 2017 5 Expires: May 2, 2018 7 SET Security Event Stream Management and Provisioning 8 draft-hunt-secevent-stream-mgmt-00 10 Abstract 12 This specification defines a "control plane" service which enables a 13 client (e.g. an Event Receiver) to establish, monitor, and manage a 14 Security Event Token Stream. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on May 2, 2018. 33 Copyright Notice 35 Copyright (c) 2017 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 51 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 52 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 53 2. Stream Monitoring and Configuration Retrieval . . . . . . . . 4 54 2.1. Event Stream Configuration Attributes . . . . . . . . . . 5 55 2.2. Checking Stream Configuration and Stream State . . . . . 8 56 2.3. Event Stream State Model . . . . . . . . . . . . . . . . 12 57 3. Stream Management and Provisioning . . . . . . . . . . . . . 14 58 3.1. Creating An Event Stream . . . . . . . . . . . . . . . . 14 59 3.2. Updating An Event Stream . . . . . . . . . . . . . . . . 16 60 3.2.1. Update using HTTP PUT . . . . . . . . . . . . . . . . 17 61 3.2.2. Update using HTTP PATCH . . . . . . . . . . . . . . . 19 62 4. Models for Managing Stream Subjects . . . . . . . . . . . . . 21 63 4.1. General Considerations for Managing Subjects . . . . . . 22 64 4.2. Subjects as Part of Stream Configuration . . . . . . . . 22 65 4.2.1. Checking Subject Membership . . . . . . . . . . . . . 22 66 4.2.2. Adding and Removing Subjects to a Stream . . . . . . 25 67 4.3. Subjects as Members of a Group . . . . . . . . . . . . . 27 68 4.3.1. Checking Membership . . . . . . . . . . . . . . . . . 28 69 4.3.2. Adding and Removing SCIM Users to a Group . . . . . . 29 70 4.4. Subjects as a Resource (aka POST Profile) . . . . . . . . 31 71 4.4.1. Adding A Subject to a Stream . . . . . . . . . . . . 33 72 4.4.2. Querying for Subject in Event Streams . . . . . . . . 34 73 4.4.3. Removing a Subject from an Event Stream . . . . . . . 35 74 5. Event Stream Verification . . . . . . . . . . . . . . . . . . 35 75 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37 76 6.1. Subject Management . . . . . . . . . . . . . . . . . . . 37 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 37 78 7.1. Multi-Party Access to Streams . . . . . . . . . . . . . . 37 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 80 8.1. Registration of Verify Event URI . . . . . . . . . . . . 38 81 8.2. SCIM Schema Registration . . . . . . . . . . . . . . . . 38 82 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 83 9.1. Normative References . . . . . . . . . . . . . . . . . . 39 84 9.2. Informative References . . . . . . . . . . . . . . . . . 39 85 Appendix A. Event Stream Resource Type and Schema Definitions . 40 86 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 47 87 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 47 88 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 47 90 1. Introduction and Overview 92 This specification defines a "Control Plane" service that defines how 93 an Event Receiver or its agent may provision, monitor, and manage the 94 configuration of an Event Stream that delivers Security Event Tokens 95 (see [I-D.ietf-secevent-token]) using delivery methods such as 96 specified in the SET Delivery Using HTTP Specification (see 97 [I-D.ietf-secevent-delivery]). 99 The specification defines the common metadata Event Transmitters and 100 Receivers use to describe HTTP service endpoints, methods, optional 101 signing and encryption modes, as well as the type and content of SETs 102 delivered over a Stream. The specification defines how the Event 103 Receiver parties may review and update the current configuration and 104 confirm operational delivery status using HTTP over TLS. 106 The mandatory part of this specification (see Section 2) uses a 107 profile of SCIM (see [RFC7643] and [RFC7644]) to implement Event 108 Stream configuration, monitoring and retrieval using HTTP GET 109 Section 4.3.1 [RFC7231]. Additionally, SCIM MAY be used to manage 110 and update Event Stream configuration and operational state. 112 The choice os SCIM has been recommended as it is intended as a 113 general purpose layer that can be applied to many underlying systems. 114 SCIM's extensibility mechanisms to define data types (resource types) 115 enable it to be flexibly used by specifications intenting to profile 116 SET Tokens and Delivery for use in many ways. 118 For the purposes of the Control Plane, SCIM Section 2 [RFC7643] 119 provides the JSON data definitions that enable the Control Plane to 120 allow service providers and clients to negotiate attributes and 121 resource types used in different SET Profiles. This includes 122 declarations and discovery of attribute types, mutability, 123 cardinality, and returnability that MAY differ between deployments 124 and SET Event type profiles. For HTTP protocol handling and error 125 signaling, the processing rules in [RFC7644] SHALL be applied. 127 1.1. Notational Conventions 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119] . These 132 keywords are capitalized when used to unambiguously specify 133 requirements of the protocol or application features and behavior 134 that affect the inter-operability and security of implementations. 135 When these words are not capitalized, they are meant in their 136 natural-language sense. 138 For purposes of readability examples are not URL encoded. 139 Implementers MUST percent encode URLs as described in Section 2.1 of 140 [RFC3986]. Many examples show only partial response and may use 141 "..." to indicate omitted data. 143 Throughout this documents all figures MAY contain spaces and extra 144 line-wrapping for readability and space limitations. Similarly, some 145 URI's contained within examples, have been shortened for space and 146 readability reasons. 148 1.2. Definitions 150 This specification assumes terminology defined in the Security Event 151 Token specification [I-D.ietf-secevent-token] and SET Token Delivery 152 specification [I-D.ietf-secevent-delivery]. 154 The following definitions are defined for Security Event 155 distribution: 157 Control Plane 158 A Control Plane represents an service offered by an Event 159 Transmitter that lets an Event Receiver query the current 160 operational and/or error status of an Event Stream. The Control 161 Plane MAY also be used to retrieve Event Stream and SET 162 configuration data. 164 Data Plane 165 The Data Plane represents the HTTP service offered by an Event 166 Receiver that allows the Event Transmitter to deliver multiple 167 SETs via HTTP POST as part of an Event Stream. 169 Client A Client is any actor, typically represented by an 170 authorization credential, authorized to make changes to an Event 171 Stream. Verify often this is an actor belonging to the Event 172 Receiver organization. Actors can be servers, monitoring 173 services, and administrators. 175 2. Stream Monitoring and Configuration Retrieval 177 The Control Plane is an HTTP service associated with an Event 178 Transmitter that enables the provisioning and monitoring of Event 179 Streams by entities such Event Receivers, administrators, and 180 monitoring services. This section describes required functionality 181 to enable Event Receivers to retrieve configuration attributes and to 182 detect SET delivery problems that may occur when an Event Transmitter 183 fails to deliver SETs. 185 This specification also defines optional Control Plane services to 186 create and update streams in sections Section 3 and Section 4. 188 2.1. Event Stream Configuration Attributes 190 An Event Stream is defined by a set of attributes which together 191 define an Event Stream's operational configuration: 193 eventUris 194 A read only array of JSON String values which are the URIs of 195 events configured for the Event Stream. This attribute is 196 assigned by the Control Plane provider in response to receiving an 197 Event Stream creation or update request. See "eventUris_req". 199 eventUris_req 200 An array of JSON String values which are the URIs of events 201 requested by the Event Receiver for the Stream. This attribute is 202 modifiable. An Event Stream provider MAY use this attribute to 203 request requested Event URIs over time that may not be initially 204 offered. 206 eventUris_avail 207 A read only array of JSON String values which are the URIs of 208 events that the Event Transmitter is able to support. This 209 attribute MAY be used by Control Plane clients to discover new 210 events that may become available over time. 212 methodUri 213 A REQUIRED JSON String value which represents the method used to 214 transfer SETs to the Event Receiver. See 215 [I-D.ietf-secevent-delivery]. 217 deliveryUri 218 A JSON String value containing a URI that describes the location 219 where SETs are received (e.g. via HTTP POST). Its format and 220 usage requirements are defined by the associated "methodUri". 222 iss 223 The URI for the publisher of the SETs that will be issued for the 224 Event Stream. See Section 2.1 [I-D.ietf-secevent-token]. 226 aud 227 An OPTIONAL JSON Array of JSON String values which are URIs 228 representing the audience(s) of the Event Stream. The value SHALL 229 be the value of SET "aud" claim sent to the Event Receiver. 231 iss_jwksUri 232 An OPTIONAL String that contains the URL of the SET issuers public 233 JSON Web Key Set [RFC7517]. This contains the signing key(s) the 234 Event Receiver uses to validate SET signatures from the Event 235 Transmitter that will be used by the Event Receiver to verify the 236 authenticity of issued SETs. 238 aud_jwksUri 239 An OPTIONAL JSON Web Key Set [RFC7517] that contains the Event 240 Receiver's encryption keys that MAY be used by the Event 241 Transmitter to encrypt SET tokens for the specified Event 242 Receiver. 244 status 245 An OPTIONAL JSON String keyword that indicates the current state 246 of an Event Stream. More information on the Event Stream state 247 can be found in Section 2.3. Valid keywords are: 249 "on" - indicates the Event Stream has been verified and that 250 the Feed Provider MAY pass SETs to the Event Receiver. 252 "paused" - indicates the Event Stream is temporarily suspended. 253 While "paused", SETs SHOULD be retained and delivered when 254 state returns to "on". If delivery is paused for an extended 255 period defined by the Event Transmitter, the Event Transmitter 256 MAY change the state to "off" indicating SETs are no longer 257 retained. 259 "off" - indicates that the Event Stream is no longer passing 260 SETs. While in off mode, the Event Stream configuration is 261 maintained, but new events are ignored, not delivered or 262 retained. Before returning to "on", a verification MUST be 263 performed. 265 "fail" - indicates that the Event Stream was unable to deliver 266 SETs to the Event Receiver due an unrecoverable error or for an 267 extended period of time. Unlike paused status, a failed Event 268 Stream does not retain existing or new SETs that are issued. 269 Before returning to "on", a verification MUST be performed. 271 maxRetries 272 An OPTIONAL JSON number indicating the maximum number of attempts 273 to deliver a SET. A value of '0' indicates there is no maximum. 274 Upon reaching the maximum, the Event Stream "status" attribute is 275 set to "failed". 277 maxDeliveryTime 278 An OPTIONAL number indicating the maximum amount of time in 279 seconds a SET MAY take for successful delivery per request or 280 cumulatively across multiple retries. Upon reaching the maximum, 281 the Event Stream "status" is set to "failed". If undefined, there 282 is no maximum time. 284 minDeliveryInterval 285 An OPTIONAL JSON integer that represents the minimum interval in 286 seconds between deliveries. A value of '0' indicates delivery 287 should happen immediately. When delivery is a polling method 288 (e.g. HTTP GET), it is the expected time between Event Receiver 289 attempts. When in push mode (e.g. HTTP POST), it is the interval 290 the server will wait before sending a new event or events. 292 txErr 293 An OPTIONAL JSON String keyword value. When the Event Stream has 294 "subState" set to "fail", one of the following error keywords is 295 set: 297 "connection" indicates an error occurred attempting to open a 298 TCP connection with the assigned endpoint. 300 "tls" indicates an error occurred establishing a TLS connection 301 with the assigned endpoint. 303 "dnsname" indicates an error occurred establishing a TLS 304 connection where the dnsname was not validated. 306 "receiver" indicates an error occurred whereby the Event 307 Receiver has indicated an error for which the Event Transmitter 308 is unable to correct. 310 txErrDesc 311 An OPTIONAL String value that is usually human readable that 312 provides further diagnostic detail by the indicated "txErr" error 313 code. 315 verifyNonce A String value that when changed or set by a Control 316 Plane client will cause the Event Transmitter to issue a single 317 Verify Event based on the nonce value provided (see Section 5). 318 The intent of the value is to allow the Event Receiver to confirm 319 the Verify Event received matches the value set in the 320 configuration. While this value MAY be updated (see Section 5), 321 its value is usually not returned as part of an Event Stream 322 configuration. 324 subjects 325 An OPTIONAL complex attribute containing sub objects whose sub- 326 attributes define subjects against which SETs may be issued. The 327 following sub-attributes are defined: 329 value A String which uniquely identifies a subject (or set of 330 subjects) to be included in the Stream. The format and type of 331 value is defined by the 'type' sub-attribute. 333 iss A String which contains the URI of the issuer of the subject 334 identified in the "value" attribute. When not supplied the 335 issuer is assumed to be the Event Stream issuer. 337 type A case-insensitive canonical String value which defines the 338 contents of the attribute 'value'. Valid type values are: 340 OIDC Is a String value corresponding to an OpenID Connect 341 subject. The corresponding "iss" attribute is set with the 342 OpenId Connect iss value. 344 SAML A String value that is a URI that represents the subject 345 of a SAML Identity Provider. 347 EMAIL A String Value that is the Email addresses for a 348 subject. The value SHOULD be specified according to 349 [RFC5321]. 351 PHIONE Phone numbers for the user. The value SHOULD be 352 specified according to the format defined in [RFC3966], 353 e.g., 'tel:+1-201-555-0123'. 355 User A SCIM User where value is the 'id' of a User resource in 356 the local SCIM service provider. 358 Group A SCIM Group where the value is the 'id' of a Group 359 resource in the local SCIM service provider. 361 URI A miscellaneous subject that can be identified by a URI. 363 Additional Event Stream configuration (attributes) MAY be defined as 364 extensions. The method for adding new attributes is defined in 365 Section 3.3 [RFC7643]. 367 2.2. Checking Stream Configuration and Stream State 369 An Event Receiver MAY check the current status of a Stream the Event 370 Transmitter's Control Plane service by performing an HTTP GET using 371 the provided URI from the Event Transmitter either through an 372 administrative process or via the optional Stream creation response 373 defined in Section 3.1. 375 The format of the Stream GET request and response is defined by 376 Section 3.4 [RFC7644]. 378 In addition to the basic attributes defined in Section 2 [RFC7643] 379 common to all resource types, an "EventStream" resource types uses 380 the attributes defined in Section 2.1. As with any SCIM resource, an 381 "EventStream" resource MUST include the JSON attributes "schemas" and 382 "id" as defined in [RFC7643]: 384 schemas 385 Is an array of Strings with at least a single value of 386 "urn:ietf:params:scim:schemas:event:2.0:EventStream". 387 Configuration MAY be extented through the addition of other schema 388 URI values such as in the case where a new delivery method or SET 389 profile needs to define additional attributes. 391 id 392 Is a String which is a permanent unique identifier for 393 "EventStream" resources. The value which is also used to define a 394 permanent Event Stream Resource URI. 396 The example below retrieves a specific "EventStream" resource whose 397 "id" is "548b7c3f77c8bab33a4fef40". 399 GET /EventStreams/767aad7853d240debc8e3c962051c1c0 400 Host: example.com 401 Accept: application/json 402 Authorization: Bearer h480djs93hd8 404 Figure 1: Example EventStream HTTP GET Request 406 Below is an example response to the "EventStream" retrieval made in 407 Figure 1. 409 HTTP/1.1 200 OK 410 Content-Type: application/scim+json 411 Location: 412 https://example.com/EventStreams/767aad7853d240debc8e3c962051c1c0 414 { 415 "schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"], 416 "id":"767aad7853d240debc8e3c962051c1c0", 417 "eventUris_req":[ 418 "http://schemas.openid.net/event/backchannel-logout" 419 ], 420 "eventUris":[ 421 "http://schemas.openid.net/event/backchannel-logout" 422 ], 423 "methodUri":"urn:ietf:params:set:method:HTTP:webCallback", 424 "deliveryUri":"https://notify.examplerp.com/Events", 425 "aud":"https://sets.myexamplerp.com", 426 "status":"fail", 427 "txErr":"connection", 428 "txErrDesc":"TCP connect error to notify.examplerp.com.", 429 "maxDeliveryTime":3600, 430 "minDeliveryInterval":0, 431 "description":"Logout events from oidc.example.com", 432 "meta":{ 433 ... SCIM meta attributes ... 434 } 435 } 437 Figure 2: Example Stream GET Response 439 In the above figure, the "EventStream" shows a "status" of "fail" due 440 to a TCP connection error. In this case, the Event Receiver is able 441 to discover that its endpoint was unavailable and has been marked 442 failed by the Event Transmitter (possibly explaining a lack of 443 received SETs). Typically, with this type of error, appropriate 444 operations staff would be alerted and some corrective action would be 445 taken to check for a configuration error or service failure. 447 The frequency with which Event Receivers poll the Event Stream status 448 depends on factors such as: 450 o The level of technical fault tolerance and availability of the 451 receiving endpoint. 453 o The amount of risk that can be tolerated for lost events. For 454 example, if Security Events are considered informational, then 455 infrequent (hourly or daily) may be sufficient. 457 o The amount of buffer recovery offered by an Event Transmitter 458 which MAY be minutes depending on SET frequency and buffer size. 460 In many cases Event Stream status monitoring may be triggered on a 461 timeout basis. Event Receivers would typically poll if they have not 462 received a SET for some period during which SETs would be expected 463 based on past experience. 465 Receivers MAY use the endpoint "/EventStreams" to query and retrieve 466 available Event Streams based on the provided "Authorization" header. 468 The example below retrieves any "EventStream" resources based solely 469 on the requestor's authorization header. 471 GET /EventStreams/ 472 Host: example.com 473 Accept: application/json 474 Authorization: Bearer h480djs93hd8 476 Figure 3: Example Stream HTTP GET Request From Common Endpoint 478 HTTP/1.1 200 OK 479 Content-Type: application/scim+json 480 Location: 481 https://example.com/EventStreams/767aad7853d240debc8e3c962051c1c0 483 { 484 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 485 "totalResults":1, 486 "itemsPerPage":10, 487 "startIndex":1, 488 "Resources":[ 489 { 490 "schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"], 491 "id":"767aad7853d240debc8e3c962051c1c0", 492 "feedName":"OIDCLogoutFeed", 493 "eventUris_req":[ 494 "http://schemas.openid.net/event/backchannel-logout" 495 ], 496 "eventUris":[ 497 "http://schemas.openid.net/event/backchannel-logout" 498 ], 499 "eventUris_avail":[ 500 "http://schemas.openid.net/event/backchannel-logout" 501 ], 502 "methodUri":"urn:ietf:params:set:method:HTTP:webCallback", 503 "deliveryUri":"https://notify.examplerp.com/Events", 504 "aud":"https://sets.myexamplerp.com", 505 "status":"fail", 506 "txErr":"connection", 507 "txErrDesc":"TCP connect error to notify.examplerp.com.", 508 "maxDeliveryTime":3600, 509 "minDeliveryInterval":0, 510 "description":"Logout events from oidc.example.com", 511 "meta":{ 512 ... SCIM meta attributes ... 513 }] 514 } 516 Figure 4: Example Event Stream List/Query Response Form 518 2.3. Event Stream State Model 520 The Event Stream configuration attribute "status" reports the current 521 state of an Event Stream with regards to whether the stream is 522 operational or is in a suspended or failed state. Additionally, the 523 "status" attribute can be used to pause or stop streams using the 524 stream configuration update functions described in Section 3. 526 The following is the state machine representation of a Event Stream 527 on a Event Transmitter. Note that a Event Stream cannot be made 528 active until a verification process has been completed. As such, a 529 newly created Event Stream begins with state "on". 531 + 532 Create 533 | 534 +--------+ +------v-----+ +--------+ 535 | +-Restart-> +--Suspend-> | 536 | fail | | on | | paused | 537 | <--Error--+ <--Resume--+ | 538 +--------+ +-+-------^--+ +---+----+ 539 | | | 540 Disable Enable | 541 | | | 542 +-v-------+--+ | 543 | off <--Limited-----+ 544 +------------+ 546 Figure 5: Event Stream States at Event Transmitter 548 In Figure 5, the following actions impact the operational state of an 549 Event Stream. "status" values are shown in the boxes, and change 550 based on the following actions: 552 Create 553 A Event Receiver or an administrator creates a new Event Stream as 554 described in Section 3.1. The initial state is "on". 556 Error 557 An Event Transmitter that has not been able to deliver a SET over 558 one or more retries which has reached a limit of attempts 559 ("maxRetries") or time ("maxDeliveryTime") MAY set the Event 560 Stream state to "fail". What stream status is set to "failed", 561 the Event Transmitter is indicating that SETs are being lost and 562 may not be recoverable. 564 Limited 565 A paused Event Stream has reached the transmitters ability to 566 retain SETs for delivery. The Event Transmitter changes the state 567 to "off" indicating SET loss is potentially occurring. 569 Restart 570 An administrator having corrected the failed delivery condition 571 modifies the Event Stream state to "on" (e.g. see Section 3.2). 573 Suspend and Resume 574 An Event Stream MAY be suspended and resumed by updating the Event 575 Stream state to "paused" or "on". For example, see see 576 Section 3.2. While suspended, the Event Transmitter retains 577 undelivered SETs for a period of time and resources specified by 578 the Event Transmitter (see "Limited"). 580 Enable and Disable 581 A Event Stream MAY be disabled and enabled by updating the Event 582 Stream "state" to "off" or "on". For example, see see 583 Section 3.2. While the Event Stream is disabled, all SETs that 584 occur at the Event Transmitter are lost. 586 3. Stream Management and Provisioning 588 This section describes optional Stream management provisioning 589 features that allow receivers or provisioning systems to create 590 streams and update configuration to perform actions such as rotation, 591 and operational state (e.g. suspend, stop, or resume) management. 593 The operations specified in this section are based on [RFC7644]. 594 SCIM schema declarations for the "EventStream" resources are defined 595 in Appendix A. HTTP Protocol usage and processing rules are provided 596 by [RFC7644]. 598 3.1. Creating An Event Stream 600 To define an Event Stream, the Event Receiver or its administrator 601 (known as the client) first obtains an authorization credential 602 allowing the ability to define a new Stream. Note: the process for 603 registering to obtain credentials and permission to register is out- 604 of-scope of this specification. 606 Upon obtaining authorization, the client issues an HTTP POST request 607 as defined in Section 3.3 [RFC7644]. To complete the request, the 608 administrative entity provides the required Stream configuration 609 attributes as specified in Section 2.1, the delivery method 610 [I-D.ietf-secevent-delivery] and any additional configuration 611 specified by the SET Event Specifications that are being used. 613 The client MAY discover the Event Transmitter's Control Plane service 614 for the schema requirements for "EventStream" resource type and any 615 other extensions using SCIM schema discovery in Section 4 [RFC7644]. 617 The process to create an Event Stream is as follows: 619 1. The client initiates an HTTP POST to the Control Plane endpoint 620 and provides a JSON document defining an EventStream which 621 contains information about the Event Receivers endpoints, 622 settings, and keys. 624 2. Upon validating the request, the Event Transmitters control plane 625 provisions the stream and updates the EventStream configuration 626 with the corresponding Event Transmitter information. 628 3. The Control Plane responds to the request from step 1 and returns 629 the final representation of the Event Stream configuration along 630 with a pointer to the created EventStream resource that the 631 client MAY use to monitor status and update configuration. 633 4. Upon receiving the response, the client completes the client side 634 configuration and provisioning based upon the returned 635 EventStream configuration. 637 In the following non-normative example, a request to create a new 638 "EventStream" is submitted. 640 POST /EventStreams 641 Host: example.com 642 Accept: application/scim+json 643 Content-Type: application/scim+json 644 Authorization: Bearer h480djs93hd8 646 { 647 "schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"], 648 "feedName":"OIDCLogoutFeed", 649 "eventUris_req":[ 650 "http://schemas.openid.net/event/backchannel-logout" 651 ], 652 "methodUri":"urn:ietf:params:set:method:HTTP:webCallback", 653 "deliveryUri":"https://notify.examplerp.com/Events", 654 "aud":"https://sets.myexamplerp.com", 655 "maxDeliveryTime":3600, 656 "minDeliveryInterval":0, 657 "description":"Logout events from oidc.example.com" 658 } 660 Figure 6: Example Create Event Stream Request 662 In following non-normative response, the Control Plane provider has 663 automatically assigned an HTTP addressable location for the 664 EventStream resource as well as an "id". Additionally, the Control 665 Plane response below includes additional configuration data for "iss" 666 and "iss_jwksUri". 668 HTTP/1.1 201 Created 669 Content-Type: application/scim+json 670 Location: 671 https://example.com/v2/EventStreams/767aad7853d240debc8e3c962051c1c0 673 { 674 "schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"], 675 "id":"767aad7853d240debc8e3c962051c1c0", 676 "feedName":"OIDCLogoutFeed", 677 "eventUris_req":[ 678 "http://schemas.openid.net/event/backchannel-logout" 679 ], 680 "eventUris":[ 681 "http://schemas.openid.net/event/backchannel-logout" 682 ], 683 "eventUris_avail":[ 684 "http://schemas.openid.net/event/backchannel-logout" 685 ], 686 "methodUri":"urn:ietf:params:set:method:HTTP:webCallback", 687 "deliveryUri":"https://notify.examplerp.com/Events", 688 "aud":"https://sets.myexamplerp.com", 689 "status":"on", 690 "maxDeliveryTime":3600, 691 "minDeliveryInterval":0, 692 "iss":"oidc.example.com" 693 "iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks" 694 "description":"Logout events from oidc.example.com", 695 "meta":{ 696 ... SCIM meta attributes ... 697 } 698 } 700 Figure 7: Example Response to Create EventStream Request 702 3.2. Updating An Event Stream 704 Two HTTP methods are available to update an Event Stream 705 configuration. 707 The HTTP PUT operation accepts a JSON Document representing an 708 existing EventStream configuration and replaces it. 710 An optional HTTP PATCH operation uses a JSON Patch [RFC6902] style 711 request format to allow manipulation of specific EventStream 712 configuration such as (but not limited to) "status", and 713 "subjects". 715 3.2.1. Update using HTTP PUT 717 The HTTP PUT method allows a client having previously received the 718 EventStream JSON document to modify the document and replace the 719 Control Plane provider's copy. In using this method, the client is 720 not required to remove data normally asserted or defined by the Event 721 Stream Control Plane provider (e.g. attributes that are read only). 722 The processing rules of [RFC7644] enable the client to "put back" 723 what was previously received allowing the Control Plane provider to 724 figure out what attributes need updating and which attributes are 725 ignored. For example, while "id" is immutable, the Control Plane 726 provider will simply ignore attempts to replace its value. When 727 processing is complete the final accepted state is represented in the 728 HTTP Response. 730 In the following non-normative example, a request to replace the 731 existing EventStream "EventStream" is submitted. In this example, 732 the change shown is the status is now set to "off". Note that the 733 client does not have to remove read-only attributes such as 734 "eventUris" and "eventUris_avail" as these values are ignored as per 735 Section 3.5.1 [RFC7644]. 737 PUT /EventStreams/767aad7853d240debc8e3c962051c1c0 738 Host: example.com 739 Accept: application/scim+json 740 Content-Type: application/scim+json 741 Authorization: Bearer h480djs93hd8 743 { 744 "schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"], 745 "id":"767aad7853d240debc8e3c962051c1c0", 746 "feedName":"OIDCLogoutFeed", 747 "eventUris_req":[ 748 "http://schemas.openid.net/event/backchannel-logout" 749 ], 750 "eventUris":[ 751 "http://schemas.openid.net/event/backchannel-logout" 752 ], 753 "eventUris_avail":[ 754 "http://schemas.openid.net/event/backchannel-logout" 755 ], 756 "methodUri":"urn:ietf:params:set:method:HTTP:webCallback", 757 "deliveryUri":"https://notify.examplerp.com/Events", 758 "aud":"https://sets.myexamplerp.com", 759 "status":"off", 760 "maxDeliveryTime":3600, 761 "minDeliveryInterval":0, 762 "iss":"oidc.example.com" 763 "iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks" 764 "description":"Logout events from oidc.example.com", 765 "meta":{ 766 ... SCIM meta attributes ... 767 } 768 } 770 Figure 8: Example Replace Event Stream Request 772 In following non-normative response, the Control Plane provider 773 responds with the processed final state of the submitted EventStream. 775 HTTP/1.1 200 OK 776 Content-Type: application/scim+json 777 Location: 778 https://example.com/v2/EventStreams/767aad7853d240debc8e3c962051c1c0 780 { 781 "schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"], 782 "id":"767aad7853d240debc8e3c962051c1c0", 783 "feedName":"OIDCLogoutFeed", 784 "eventUris_req":[ 785 "http://schemas.openid.net/event/backchannel-logout" 786 ], 787 "eventUris":[ 788 "http://schemas.openid.net/event/backchannel-logout" 789 ], 790 "eventUris_avail":[ 791 "http://schemas.openid.net/event/backchannel-logout" 792 ], 793 "methodUri":"urn:ietf:params:set:method:HTTP:webCallback", 794 "deliveryUri":"https://notify.examplerp.com/Events", 795 "aud":"https://sets.myexamplerp.com", 796 "status":"off", 797 "maxDeliveryTime":3600, 798 "minDeliveryInterval":0, 799 "iss":"oidc.example.com" 800 "iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks" 801 "description":"Logout events from oidc.example.com", 802 "meta":{ 803 ... SCIM meta attributes ... 804 } 805 } 807 Figure 9: Example Response to PUT EventStream Request 809 3.2.2. Update using HTTP PATCH 811 Periodically, Event Receiver parties MAY have need to update an 812 EventStream configuration for the purpose of: 814 o Rotating access credentials or keys 816 o Updating endpoint configuration 818 o Making operational changes such as pausing, resetting, or 819 disabling an Event Stream. 821 o Other operations (e.g. such as adding or removing subjects) as 822 defined by profiling Event specifications. 824 As documented in Section 3.5.2 [RFC7644], one or more PATCH 825 operations (which are based on [RFC6902]) can be made against a 826 single EventStream resource. The update is expressed as a JSON 827 document. The JSON document contains an attribute "Operations" which 828 contains an array of JSON objects each of which each have the 829 following attributes: 831 op 832 A JSON attribute whose value is one of "add", "remove", or 833 "replace". 835 path 836 A JSON attribute whose value is a document attribute path (see 837 Section 3.5.2 [RFC7644]) describing the attribute or sub-attribute 838 or value to be updated in the case of multi-valued complex 839 attributes such as "subjects". 841 value 842 The value to be assigned to the JSON document attribute defined in 843 "path". 845 In the following non-normative example, the client requests that the 846 "status" configuration attribute be changed to "paused" for the 847 EventStream whose path is identified by the request URI path. 849 PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0 850 Host: example.com 851 Accept: application/scim+json 852 Content-Type: application/scim+json 853 Authorization: Bearer h480djs93hd8 855 { 856 "schemas": 857 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 858 "Operations": [{ 859 "op":"replace", 860 "path":"status", 861 "value":"paused" 862 }] 863 } 865 Figure 10: Example EventStream PATCH Request 867 In the above figure, upon receiving the request, the Event 868 Transmitter would stop sending Events to the Receiver based on the 869 requested value of "status" being set to "paused". 871 In the following non-normative example, the client requests the 872 addition and removal of two subjects from an existing EventStream. 873 This operation is discussed further in Section 4.2. 875 PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0 876 Host: example.com 877 Accept: application/scim+json 878 Content-Type: application/scim+json 879 Authorization: Bearer h480djs93hd8 881 { 882 "schemas": 883 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 884 "Operations": [{ 885 "op":"add", 886 "path":"subjects", 887 "value":{ 888 "type":"EMAIL", 889 "value":"alice@example.com" 890 } 891 }, 892 { 893 "op":remove", 894 "path":"subjects[value eq \"bob@example.com\"] 895 }] 896 } 898 Figure 11: Example Changing the Members of EventStream 900 In the above request, the second operation, the remove operation, 901 uses a "path" attribute to specify a matching filter the correct 902 array element of "subjects" by matching the appropriate sub- 903 attributes which are denoted by square brackets (see Figure 1 and 2 904 [RFC7644] for other examples and ABNF for filters). In this case the 905 composite filter of the "subjects" sub-attributes "type" and "value" 906 are used to remove the correct JSON array element. Upon receiving 907 the request, the EventStream subjects attribute would be updated to 908 reflect the changes. 910 4. Models for Managing Stream Subjects 912 The extensibility of SCIM enables many ways to model subjects that 913 are part of an Event Stream. This section explores a few 914 alternatives that profiling specifications could use to manage the 915 contents of an Event Stream. These examples include managing 916 subjects: 918 o As an attribute of an Event Stream configuration (see 919 Section 4.2); 921 o As a member of SCIM Group (see Section 4.3); and, 923 o As a specific Subject resource (see Section 4.4). 925 4.1. General Considerations for Managing Subjects 927 As a privacy and scalability consideration, profiling specifications 928 SHOULD consider that most deployments SHOULD not allow the subjects 929 that are part of an Event Stream to be enumerated in a single 930 request. For example, in Section 4.2, the Event Stream configuration 931 attribute "subjects" is typically not returned when querying Event 932 Stream configurations (see Section 2.2). This is because the number 933 of values may be too large (e.g. great than 100k values or even in 934 the billions or more). Further, depending on the Security Event 935 types being exchanged, Event Receivers MAY confirm that a subject is 936 part of a stream for privacy reasons. 938 The ability to return attributes such as "subjects" is indicated by 939 Control Plane service providers in schema discovery (see Section 4 940 [RFC7644]) as the schema attribute "returned". For "subjects" this 941 attribute SHOULD be set to "request" or "never". In "request" mode, 942 the client must specifically request the attribute "subjects" to have 943 it enumerated. If the mode is _never_, the attribute SHALL NOT be 944 returned to clients. In all cases however, a client MAY execute a 945 query to verify the presence of a subject: 947 4.2. Subjects as Part of Stream Configuration 949 In this section, examples are given using the "subjects" attribute of 950 Event Stream configuration described in Section 2.1 952 The following sections assume subject membership within streams is 953 defined by the "subjects" attribute of the Event Stream 954 configuration. As defined, subjects can support a number of value 955 types including: OIDC Connect Subjects, SCIM Users and Groups, e-mail 956 and telephone number identifiers, and URI referencable entities. 958 4.2.1. Checking Subject Membership 960 Checking subject membership is a matter of performing a query using a 961 filter to achieve a match based on a value of the "subjects" 962 attribute. 964 4.2.1.1. Email Based Subjects 966 In this section, values have been added to the "subjects" attribute 967 that are email addresses which clients to the Control Plane would 968 like to verify are present or not. The "subjects" attribute has sub- 969 attribute "type" set to "EMAIL" and the sub-attribute "value" 970 contains an email address. 972 In the following non-normative example, a client queries the Control 973 Plane to see if "alice@example.com" is part of any defined stream 974 configuration. In the request, only the attribute "id" of the Event 975 Stream is requested as the client does not need to see the rest of 976 the Event Stream attributes. Note, for readability, the URL is not 977 encoded. 979 GET /EventStreams?filter=(subjects.value eq "alice@example.com") 980 &attributes=id 981 Host: example.com 982 Accept: application/scim+json 983 Authorization: Bearer h480djs93hd8 985 Figure 12: Determining if an EMail Subject is in an Event Stream 987 In this non-normative example response, the subject is confirmed as 988 not part of any Event Streams associated with the requester. In this 989 case an empty list is returned with no values and "totalResults" is 990 "0". 992 HTTP/1.1 200 OK 993 Content-Type: application/scim+json 995 { 996 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 997 "totalResults":0, 998 "Resources":[] 999 } 1001 Figure 13: Example Response With No Subject Match 1003 In the response below, a match for subject "alice@example.com" is 1004 found and the "id" of the Event Stream configuration that contains 1005 the subject is returned is "767aad7853d240debc8e3c962051c1c0". 1007 HTTP/1.1 200 OK 1008 Content-Type: application/scim+json 1010 { 1011 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1012 "totalResults":1, 1013 "Resources":[ 1014 { 1015 "id":"767aad7853d240debc8e3c962051c1c0", 1016 ...other meta attributes... 1017 } 1018 ] 1019 } 1021 Figure 14: Example Response With Single Match 1023 4.2.1.2. OIDC Based Subjects 1025 In this section, values in the "subjects" attribute are OIDC users 1026 which clients would like to verify are present. The attribute 1027 "subjects" has the sub-attribute "type" set to "OIDC" and the sub- 1028 attribute "value" contains an OIDC "sub" value and the "iss" sub- 1029 attribute contains the corresponding OIDC Provider "iss" value. For 1030 this example, the OIDC "iss" is "op.example.com" and the "sub" is 1031 "123456". 1033 In the following non-normative example, a client queries the Control 1034 Plane to see if the above OIDC user is part of any defined stream 1035 configuration. In the request, only the attribute "id" is requested. 1036 Note, for readability, the URL is not encoded. 1038 GET /EventStreams?filter=(subjects[value eq "123456" and 1039 iss eq "op.example.com"])&attributes=id 1040 Host: example.com 1041 Accept: application/scim+json 1042 Authorization: Bearer h480djs93hd8 1044 Figure 15: Determining if an OIDC Subject is in an Event Stream 1046 In the above request note that "iss" and "value" are enclosed within 1047 square brackets. This is done, per Figure 1 [RFC7644] to ensure the 1048 matching condition within "[" and "]" is matched against the same 1049 JSON array record. If the filter was expressed as "(subjects.value 1050 eq "123456" and subjects.iss eq "op.example.com")" Then an improper 1051 match may occur because a composite value of "subjects" may have 1052 "123456" while another has "op.example.com". 1054 For examples of responses to Figure 15, see Figure 13 and Figure 14 1056 4.2.2. Adding and Removing Subjects to a Stream 1058 Adding and removing subjects to an Event Stream is performed using 1059 the HTTP PATCH method described in Section 3.2.2. The following 1060 provides examples of adding and removing subjects based on EMAIL and 1061 OIDC subects. 1063 In the following non-normative example, the client requests the 1064 addition of a subject identified by an EMAIL address to an existing 1065 EventStream. The composite value of subjects has the sub-attributes 1066 "type" and "value" which are assigned. 1068 PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0 1069 Host: example.com 1070 Accept: application/scim+json 1071 Content-Type: application/scim+json 1072 Authorization: Bearer h480djs93hd8 1074 { 1075 "schemas": 1076 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1077 "Operations": [{ 1078 "op":"add", 1079 "path":"subjects", 1080 "value":{ 1081 "type":"EMAIL", 1082 "value":"alice@example.com" 1083 } 1084 }] 1085 } 1087 Figure 16: Adding an EMAIL Subject to a Stream 1089 In the following non-normative example, the client requests the 1090 addition of an OIDC subject to an existing EventStream. The 1091 composite value of "subjects" has the sub-attributes "type", "iss", 1092 and "value" which are assigned. 1094 PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0 1095 Host: example.com 1096 Accept: application/scim+json 1097 Content-Type: application/scim+json 1098 Authorization: Bearer h480djs93hd8 1100 { 1101 "schemas": 1102 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1103 "Operations": [{ 1104 "op":"add", 1105 "path":"subjects", 1106 "value":{ 1107 "type":"OIDC", 1108 "value":"123456", 1109 "iss":"op.example.com" 1110 } 1111 }] 1112 } 1114 Figure 17: Adding an OIDC Provider Subject to a Stream 1116 In the following non-normative example, the client requests the 1117 removal of a subject selected by using a filter against the 1118 "subjects" attribute. 1120 PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0 1121 Host: example.com 1122 Accept: application/scim+json 1123 Content-Type: application/scim+json 1124 Authorization: Bearer h480djs93hd8 1126 { 1127 "schemas": 1128 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1129 "Operations": [{ 1130 "op":"remove", 1131 "path":"subjects[value eq \"123456\" and iss eq \"op.example.com\"]", 1132 }] 1133 } 1135 Figure 18: Removing an OIDC Connect Subject from a Stream 1137 4.3. Subjects as Members of a Group 1139 SCIM defines a resource type called a "Group" which can be used as a 1140 container to manage one or more objects in a collection (See 1141 Section 4.2 of [RFC7643]). Groups work in similar fashion to the 1142 operations described in Section 4.2 except instead of operations 1143 against the '"subjects", the "members" attribute is used. Typically 1144 the value of the members attribute is the "id" of a local User or 1145 Group. 1147 In order to use this method, the Stream configuration indicates the 1148 SCIM Group being used by adding Group as a member of the "subjects" 1149 attribute of the Stream configuration and indicating a "type" of 1150 "Group". 1152 The following is an example Stream configuration that has a Group as 1153 a member of the subjects. In the example below, "e18c2dfb5d588" is 1154 the identifier of a SCIM Group containing a list of member resources. 1156 { 1157 "schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"], 1158 "id":"767aad7853d240debc8e3c962051c1c0", 1159 "feedName":"OIDCLogoutFeed", 1160 "eventUris":[ 1161 "http://schemas.openid.net/event/backchannel-logout" 1162 ], 1163 "methodUri":"urn:ietf:params:set:method:HTTP:webCallback", 1164 "deliveryUri":"https://notify.examplerp.com/Events", 1165 "aud":"https://sets.myexamplerp.com", 1166 "status":"off", 1167 "maxDeliveryTime":3600, 1168 "minDeliveryInterval":0, 1169 "iss":"oidc.example.com" 1170 "subjects":[ 1171 { 1172 "type":"Group" 1173 "value":"e18c2dfb5d588" 1174 } 1175 ] 1176 "iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks" 1177 "description":"Logout events from oidc.example.com", 1178 "meta":{ 1179 ... SCIM meta attributes ... 1180 } 1181 } 1183 Figure 19: Event Stream Configured to Use SCIM Group 1185 4.3.1. Checking Membership 1187 In this section, values have been added to the "members" attribute 1188 are "id" values of known SCIM resources. These values can be queried 1189 against the Group to see if the "id" is a member. 1191 If the requester does not know the "id" of the resource for which 1192 they would like to check membership, a query can be performed as 1193 described in Section 3.4 [RFC7644]. 1195 In the following non-normative example, a client queries the Control 1196 Plane to see if a User with "id" value of "413861904646" is a part of 1197 any Group. . 1199 GET /Groups?filter=members.value eq "413861904646" 1200 &attributes=id 1201 Host: scim.example.com 1202 Accept: application/scim+json 1203 Authorization: Bearer h480djs93hd8 1205 Figure 20: Determining if a SCIM Resource is in a Event Stream 1206 Example 1208 In this non-normative response, the "id" is confirmed as not part of 1209 the Group queried by the requester. In this case an empty list is 1210 returned with no values and "totalResults" is "0". 1212 HTTP/1.1 200 OK 1213 Content-Type: application/scim+json 1215 { 1216 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1217 "totalResults":0, 1218 "Resources":[] 1219 } 1221 Figure 21: Example Response With No Match 1223 In the response below, a match for resource with an "id" value of 1224 "413861904646" is found and the "id" of any matched Groups that 1225 contain the "id" is returned. In this case a "Group" with an "id" 1226 value of _e18c2dfb5d588_ is returned. 1228 HTTP/1.1 200 OK 1229 Content-Type: application/scim+json 1231 { 1232 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1233 "totalResults":1, 1234 "Resources":[ 1235 { 1236 "id":"e18c2dfb5d588", 1237 } 1238 ] 1239 } 1241 Figure 22: Example Response With Single Match 1243 4.3.2. Adding and Removing SCIM Users to a Group 1245 Adding and removing Users to an Event Stream Group is performed using 1246 the HTTP PATCH method described in Section 3.2.2. The following 1247 provides examples of adding and removing "Users" to a "Group" 1248 In the following non-normative example, the client requests the 1249 addition of a User identified by an "id" to an existing "Group" which 1250 is used by an Event Stream to denote member subjects. 1252 PATCH /Groups/e18c2dfb5d588 1253 Host: example.com 1254 Accept: application/scim+json 1255 Content-Type: application/scim+json 1256 Authorization: Bearer h480djs93hd8 1258 { 1259 "schemas": 1260 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1261 "Operations": [{ 1262 "op":"add", 1263 "path":"members", 1264 "value":{ 1265 "type":"User", 1266 "value":"8c16-01f8e146b87a" 1267 } 1268 }] 1269 } 1271 Figure 23: Example Adding a User to a Group 1273 In the following non-normative example, the client requests the 1274 removal of a User identified by "id" with value "8c16-01f8e146b87a". 1275 The item to be removed is selected by using a filter against the 1276 "members" attribute. 1278 PATCH /Groups/e18c2dfb5d588 1279 Host: example.com 1280 Accept: application/scim+json 1281 Content-Type: application/scim+json 1282 Authorization: Bearer h480djs93hd8 1284 { 1285 "schemas": 1286 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1287 "Operations": [{ 1288 "op":"remove", 1289 "path":"members.value eq \"8c16-01f8e146b87a\"", 1290 }] 1291 } 1293 Figure 24: Example Removing a User from a Group 1295 4.4. Subjects as a Resource (aka POST Profile) 1297 This section demonstrates how to model subject participation in an 1298 Event Stream by treating subjects as a resource (a "Subject"). In 1299 this model, a subject is added, removed, and queried from an Event 1300 Stream by through HTTP POST, DELETE, and GET methods. 1302 In this model, a new SCIM resource type is defined that describes the 1303 "Subject" resource and its associated schema. 1305 The following is a non-normative example of a Resource Type 1306 definition that is configured in a SCIM service provider. The 1307 Resource Type defines the "Subjects" endpoint as well as a URI for 1308 the schema definition. The Resource Type configuration can be 1309 discovered by querying the SCIM service provider's "/ResourceTypes" 1310 endpoint (see Section 4 [RFC7644]). 1312 { 1313 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 1314 "id": "Subject", 1315 "name": "Subject", 1316 "endpoint": "/Subjects", 1317 "description": "Endpoint managing SECEVENT Subjects.", 1318 "schema": "urn:ietf:params:scim:schemas:event:2.0:Subject", 1319 "schemaExtensions": [] 1320 } 1322 Figure 25: Example Resource Type Definition for Subjects 1324 The following is an example schema definition for a Subject resource. 1325 This configuration can be retrieved from the SCIM Service Provider 1326 using the "/Schemas" endpoint (see Section 4 [RFC7644]). 1328 { 1329 "id" : "urn:ietf:params:scim:schemas:event:2.0:Subject", 1330 "name" : "Subject", 1331 "description" : "Subject stream configuration", 1332 "attributes" : [ 1333 { 1334 "name" : "email", 1335 "type" : "string", 1336 "multiValued" : false, 1337 "description" : "The email of the subject being added to Event 1338 Streams. The value SHOULD be specfied according to [RFC5321].", 1339 "required" : true, 1340 "caseExact" : false, 1341 "mutability" : "readWrite", 1342 "returned" : "default", 1343 "uniqueness" : "none" 1344 }, 1345 { 1346 "name" : "displayName", 1347 "type" : "string", 1348 "multiValued" : false, 1349 "description" : "A simple representation of a Subject's name 1350 that can be used for display purposes.", 1351 "required" : false, 1352 "caseExact" : false, 1353 "mutability" : "readWrite", 1354 "returned" : "default", 1355 "uniqueness" : "none" 1356 }, 1357 { 1358 "name" : "streamId", 1359 "type" : "string", 1360 "multiValued" : fase, 1361 "description" : "An Event Stream a Subject is part 1362 of as identified by EventStream id", 1363 "required" : false, 1364 "mutability" : "readWrite", 1365 "returned" : "default" 1366 } 1367 ] 1368 } 1370 Figure 26: Example Schema for Subject Resources 1372 4.4.1. Adding A Subject to a Stream 1374 To add a Subject to a Stream, an HTTP POST is used to create a new 1375 Subject resource which contains attributes identifying the subject 1376 and the associated Event Stream "id". 1378 The following non-normative example demonstrates adding a subject 1379 identified by "example.user@example.com" to an "EventStream" 1380 identified by "id" with value "767aad7853d240debc8e3c962051c1c0". 1382 POST /Subjects/ HTTP/1.1 1383 Host: transmitter.example.com 1384 Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= 1385 { 1386 "schemas":["urn:ietf:params:scim:schemas:event:2.0:Subject"], 1387 "email": "example.user@example.com", 1388 "streamIds": "767aad7853d240debc8e3c962051c1c0", 1389 "schemas":["urn:ietf:params:scim:schemas:event:2.0:Subject"] 1390 } 1392 Figure 27: Adding a Subject to a Stream Using POST 1394 In response the server indicates the record is created and returns a 1395 permanent URI of the entry. This URI can later be used to remove the 1396 subject from the identified EventStream. 1398 HTTP/1.1 201 Created 1399 Content-Type: application/scim+json 1400 Location: 1401 https://example.com/v2/Subjects/e3c962051c1c0 1402 { 1403 "schemas":["urn:ietf:params:scim:schemas:event:2.0:Subject"], 1404 "id": "e3c962051c1c0", 1405 "email": "example.user@example.com", 1406 "streamIds": "767aad7853d240debc8e3c962051c1c0", 1407 "meta":{ 1408 ...SCIM meta data... 1409 } 1410 } 1412 Figure 28: Response to Adding a Subject to a Stream Using POST 1414 Should the record be a duplicate Subject, the Control Plane 1415 implementation MAY choose to return the original resource 1416 registration and location with HTTP Status 200 (OK). 1418 4.4.2. Querying for Subject in Event Streams 1420 To query Subjects, SCIM filters can be used to return matching 1421 resources as per Section 3.4.2 [RFC7643] 1423 Assuming the "id" of the EventStream is known, a query can be made 1424 against that identifier and the subjects identifier - in this case, 1425 an email address. 1427 GET /Subjects?filter=(streamId eq "e3c962051c1c0" and 1428 email eq "example.user@example.com") 1430 Figure 29: Querying if a Subject is in an EventStream 1432 If a match to the request in Figure 29 is made, the following is a 1433 non-normative example response showing the matched Subject resource. 1435 HTTP/1.1 200 OK 1436 Content-Type: application/scim+json 1438 { 1439 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1440 "totalResults":1, 1441 "Resources":[ 1442 { 1443 "id":"e3c962051c1c0", 1444 "email": "example.user@example.com" 1445 "streamIds": "e3c962051c1c0", 1446 "schemas":["urn:ietf:params:scim:schemas:event:2.0:Subject"], 1447 ...additional meta data... 1448 } 1449 ] 1450 } 1452 Figure 30: Response to Query 1454 To see if an email address is present in multiple EventStreams, the 1455 following query MAY be used. 1457 GET /Subjects?filter=(email eq "example.user@example.com") 1459 Figure 31: Querying All Event Streams for Subject 1461 Assuming only one match is found, than a response similar to 1462 Figure 30 is returned. If not matches occur, a response is returned 1463 with "totalResults" equal to 0. If more than one match is returned, 1464 the additional matches are returned in the "Resources" array. 1466 4.4.3. Removing a Subject from an Event Stream 1468 Assuming the "id" of the Subject resource is known, HTTP DELETE MAY 1469 be used. If it is not known, the "id" MAY be queried as per 1470 Section 4.4.2. 1472 To remove a Subject resource perform an HTTP DELETE using the 1473 resource's URI (see Section 3.6 [RFC7644]). 1475 DELETE /Subjects/e3c962051c1c0 1477 Figure 32: Removing a Subject from an Event Stream 1479 5. Event Stream Verification 1481 In the verify process, the Event Receiver organization initiates a 1482 request to the Event Transmitter to verify the Stream is working 1483 correctly. This can be used to both test for configuration errors 1484 (e.g. incorrect keys for signing and/or encryption, endpoints) and to 1485 verify operational state by using a Verify Event as an occasional 1486 'ping' test. 1488 To initiate a Verify Event, the Event Receiver organization using the 1489 Control Plane to set a nonce value for the Stream Configuration 1490 attribute "verifyConfirm". Once set, the Event Transmitter SHALL 1491 issue a Verify SET the includes the client specified nonce value. 1493 In the following non-normative example, the client requests a Verify 1494 Event by setting the attribute "verifyNonce" as part of the Event 1495 Stream configuration. 1497 PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0 1498 Host: example.com 1499 Accept: application/scim+json 1500 Content-Type: application/scim+json 1501 Authorization: Bearer h480djs93hd8 1503 { 1504 "schemas": 1505 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1506 "Operations": [{ 1507 "op":"replace", 1508 "path":"verifyNonce", 1509 "value":"VGhpcyBpcyBhbi" 1510 }] 1511 } 1513 Figure 33: Requesting a Verify using PATCH 1515 Upon the changing of the Event Stream configuration attribute 1516 "verifyNonce", the Event Transmitter sends a Verify Event SET to the 1517 Event Receiver using the registered "methodUri" mechanism. 1519 The Verify SET contains the following attributes: 1521 events 1522 Set with an event attribute of 1523 "urn:ietf:params:secevent:verification" and contains the sub- 1524 attribute "nonce" which contains the value of "verifyNonce" . 1526 iss 1527 Set to the URI defined in the Event Stream configuration. 1529 aud 1530 MUST be set to a value that matches the EventStream "aud" value 1531 agreed to. 1533 If the Event Stream is configured to encrypt SETs for the Event 1534 Receiver, then the SET MUST be encrypted with the provided key. 1535 Successful parsing of the message confirms that provides confirmation 1536 of correct configuration and possession of keys. 1538 The following is a non-normative JSON representation of a Verify 1539 Event issued to an Event Receiver. Included in the SET is an example 1540 nonce value "VGhpcyBpcyBhbi". 1542 { 1543 "jti": "123456", 1544 "iss": "https://transmitter.example.com", 1545 "aud": "receiver.example.com", 1546 "iat": "1493856000", 1547 "events": [ 1548 "urn:ietf:params:secevent:verification" : { 1549 "nonce": "VGhpcyBpcyBhbi", 1550 }, 1551 ], 1552 } 1554 Figure 34: Example Verification SET 1556 The above SET is encoded as a JWT and transmitted to the Event 1557 Receiver using the configured delivery method. 1559 Upon receiving a verify SET, the Event Receiver SHALL parse the SET 1560 and verify its claims. In particular, the Event Receiver SHALL 1561 confirm that the values for "nonce" match the value assigned to 1562 "verifyNonce" in the Event Stream Configuration via the Control 1563 Plane. If the values do not match, administrative action should be 1564 taken to address the mis-configuration. Similarly if the SET is not 1565 received or is unparseable, the Event Receiver organization can check 1566 Event Stream configuration and check for errors by reviewing the 1567 Stream configuration attributes "status" and "txErr". 1569 6. Privacy Considerations 1571 See Section 7.5 [RFC7644] for protocol specific privacy 1572 considerations. 1574 The Privacy Considerations of SET Token Specification 1575 [I-D.ietf-secevent-token] and the SET Token Delivery specification 1576 [I-D.ietf-secevent-delivery] SHALL apply. 1578 6.1. Subject Management 1580 The exact set of subject entities upon which SETs can be issued 1581 SHOULD NOT be made available to any single party. This is because a 1582 subject's relationship with an Event Transmitter MAY change over time 1583 and may not be known to the Event Receiver. A design consideration 1584 is that an Event Receiver MUST already know personal identifiers 1585 before asking an Event Transmitter if there is an existing 1586 relationship by asking if that personal identifier is part of a 1587 stream. Accordingly the "subjects" attribute of an Event Stream can 1588 not normally be returned. Instead, a Control Plane provider MAY 1589 confirm a subject is part of a stream. See Section 4.1 and 1590 Section 4.2.1. 1592 When receiving a request from a Control Plane client to add a 1593 subject, the provider SHOULD consider if the subject is appropriate 1594 to the purpose of the Event Stream being managed. For example, for 1595 an OpenID Connect Provider, was consent obtained to share security 1596 data with the Relying Party. Such authorization may have been 1597 previously authorized by a user via the OpenID consent process. 1598 Having obtained consent, the Control Plane provider SHOULD consider 1599 if the SET Events being requested to be streamed are appropriate. 1601 7. Security Considerations 1603 This specification depends on the Security Considerations of 1604 [RFC7644]. 1606 7.1. Multi-Party Access to Streams 1608 Implementations SHOULD support access roles which enable different 1609 types of access to Event Streams via the Control Plane service. A 1610 minimal suggested set of roles includes: 1612 Monitor For clients to retrieve Event Stream configuration and 1613 obtain current status. Access is limited to read-only operations. 1615 Control Adds the ability to modify the "status" attribute to control 1616 the operational state of the Event Stream in addition to the 1617 rights granted by "Monitor". 1619 Manage Provides the ability to list, create and manage Event Streams 1620 including updating and verifying subjects. 1622 Typically these roles are rights or scopes associated with the 1623 security credential presented in the HTTP Authorization header of 1624 requests (see Section 7 [RFC7644]). The method by which these roles 1625 are implemented is out of scope of this specification. 1627 8. IANA Considerations 1629 8.1. Registration of Verify Event URI 1631 IANA is requested to add an entry to the 'IETF URN Sub-namespace for 1632 Registered Protocol Parameter Identifiers' registry and create a sub- 1633 namespace for the Registered Parameter Identifier as per [RFC3553]: 1634 "urn:ietf:params:secevent:verification". 1636 The identifier is used to indicate a Verify Event as defined in 1637 Section 5 for use in the "events" attribute defined in 1638 [I-D.ietf-secevent-token]. 1640 8.2. SCIM Schema Registration 1642 As per the "SCIM Schema URIs for Data Resources" registry established 1643 by Section 10.3 [RFC7643], the following defines and registers the 1644 following SCIM URIs and Resource Types for Feeds and Event Streams. 1646 +---------------------------+----------+--------------+-------------+ 1647 | Schema URI | Name | ResourceType | Reference | 1648 +---------------------------+----------+--------------+-------------+ 1649 | urn:ietf:params:scim: | SET | EventStream | Section 2.1 | 1650 | schemas:event:2.0: | Event | | | 1651 | EventStream | Stream | | | 1652 +---------------------------+----------+--------------+-------------+ 1654 Attributes for SET Event Streams are defined in Section 2.1 1656 SCIM Schema and ResourceType definitions are defined in Appendix A 1658 9. References 1660 9.1. Normative References 1662 [I-D.ietf-secevent-delivery] 1663 Hunt, P., Scurtescu, M., Ansari, M., Nadalin, A., and A. 1664 Backman, "SET Token Delivery Using HTTP", draft-ietf- 1665 secevent-delivery-00 (work in progress), July 2017. 1667 [I-D.ietf-secevent-token] 1668 Hunt, P., Denniss, W., Ansari, M., and M. Jones, "Security 1669 Event Token (SET)", draft-ietf-secevent-token-02 (work in 1670 progress), June 2017. 1672 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1673 Requirement Levels", BCP 14, RFC 2119, 1674 DOI 10.17487/RFC2119, March 1997, 1675 . 1677 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1678 Resource Identifier (URI): Generic Syntax", STD 66, 1679 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1680 . 1682 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1683 DOI 10.17487/RFC5988, October 2010, 1684 . 1686 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1687 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1688 DOI 10.17487/RFC7231, June 2014, 1689 . 1691 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 1692 DOI 10.17487/RFC7517, May 2015, 1693 . 1695 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1696 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1697 . 1699 9.2. Informative References 1701 [openid-connect-core] 1702 NRI, "OpenID Connect Core 1.0", Nov 2014. 1704 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 1705 IETF URN Sub-namespace for Registered Protocol 1706 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 1707 2003, . 1709 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1710 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1711 . 1713 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 1714 DOI 10.17487/RFC5321, October 2008, 1715 . 1717 [RFC6902] Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object 1718 Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902, 1719 April 2013, . 1721 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1722 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1723 2015, . 1725 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 1726 RFC 7516, DOI 10.17487/RFC7516, May 2015, 1727 . 1729 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 1730 Mortimore, "System for Cross-domain Identity Management: 1731 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 1732 2015, . 1734 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 1735 and C. Mortimore, "System for Cross-domain Identity 1736 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 1737 September 2015, . 1739 Appendix A. Event Stream Resource Type and Schema Definitions 1741 The "EventStream" resource type definition is defined as follows: 1743 { 1744 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 1745 "id": "EventStream", 1746 "name": "EventStream", 1747 "endpoint": "/EventStreams", 1748 "description": "Endpoint and event configuration and status for SEC EVENT streams.", 1749 "schema": "urn:ietf:params:scim:schemas:event:2.0:EventStream", 1750 "schemaExtensions": [] 1751 } 1753 Figure 35: SCIM EventStream Resource Type Definition 1755 The resource type above is discoverable in the "/ResourceTypes" 1756 endpoint of a SCIM service provider and informs SCIM clients about 1757 the endpoint location of EventStream resources and the SCIM schema 1758 used to define the resource. The corresponding schema for the 1759 EventStream resource MAY be retrieved from the SCIM "/Schemas" 1760 endpoint (see Section 3.2 [RFC7644]). 1762 The attributes for the EventStream resource type are defined in 1763 Section 2.1. 1765 { 1766 "id" : "urn:ietf:params:scim:schemas:event:2.0:EventStream", 1767 "name" : "EventStream", 1768 "description" : "Event Stream Configuration", 1769 "attributes" : [ 1770 { 1771 "name" : "eventUris", 1772 "type" : "string", 1773 "multiValued" : true, 1774 "description" : "An array of String value containing a logical 1775 unique URI for Events that may be issued in the Stream", 1776 "required" : false, 1777 "caseExact" : false, 1778 "mutability" : "readOnly", 1779 "returned" : "default", 1780 "uniqueness" : "none" 1781 }, 1782 { 1783 "name" : "eventUris_req", 1784 "type" : "string", 1785 "multiValued" : true, 1786 "description" : "An array of String value containing a logical 1787 unique URI for Events that an Event Receiver is requesting.", 1788 "required" : true, 1789 "caseExact" : false, 1790 "mutability" : "readWrite", 1791 "returned" : "default", 1792 "uniqueness" : "none" 1793 }, 1794 { 1795 "name" : "eventUris_avail", 1796 "type" : "string", 1797 "multiValued" : true, 1798 "description" : "An array of String value containing a logical 1799 unique URI for Events that are supported by the Transmitter", 1800 "required" : false, 1801 "caseExact" : false, 1802 "mutability" : "readOnly", 1803 "returned" : "default", 1804 "uniqueness" : "none" 1805 }, 1806 { 1807 "name" : "methodUri", 1808 "type" : "string", 1809 "multiValued" : false, 1810 "description" : "A String value containing the URI for the 1811 method used to deliver SET events. The method used indicates 1812 the required configuration parameters for an 1813 operational Event Stream configuration.", 1814 "required" : true, 1815 "caseExact" : false, 1816 "mutability" : "readWrite", 1817 "returned" : "default", 1818 "uniqueness" : "none" 1819 }, 1820 { 1821 "name" : "deliveryUri", 1822 "type" : "string", 1823 "multiValued" : false, 1824 "description" : "A String value containing the URI for a 1825 feed endpoint used to pick up or deliver SET events based on 1826 a configured method.", 1827 "required" : true, 1828 "caseExact" : false, 1829 "mutability" : "readWrite", 1830 "returned" : "default", 1831 "uniqueness" : "none" 1832 }, 1833 { 1834 "name" : "iss", 1835 "type" : "string", 1836 "multiValued" : false, 1837 "description" : "The URI for the publisher of the SETs that will 1838 be issued for the Event Stream.", 1839 "required" : true, 1840 "caseExact" : false, 1841 "mutability" : "readWrite", 1842 "returned" : "default", 1843 "uniqueness" : "none" 1844 }, 1845 { 1846 "name" : "aud", 1847 "type" : "string", 1848 "multiValued" : true, 1849 "description" : "An OPTIONAL Array of JSON String values which 1850 are URIs representing the audience(s) of the Event Stream. 1851 Values SHALL be the value of SET "aud" claim sent to the Event 1852 Receiver.", 1853 "required" : true, 1854 "caseExact" : false, 1855 "mutability" : "readWrite", 1856 "returned" : "default", 1857 "uniqueness" : "none" 1858 }, 1859 { 1860 "name" : "iss_jwksUri", 1861 "type" : "string", 1862 "multiValued" : false, 1863 "description" : "An OPTIONAL 1864 String that contains the URL of the SET issuers public JSON 1865 Web Key Set [RFC7517]. This contains the signing key(s) the 1866 Event Receiver uses to validate SET signatures from the Event 1867 Transmitter that will be used by the Event Receiver to verify 1868 the authenticity of issued SETs.", 1869 "required" : false, 1870 "caseExact" : false, 1871 "mutability" : "readWrite", 1872 "returned" : "default", 1873 "uniqueness" : "none" 1874 }, 1875 { 1876 "name" : "aud_jwksUri", 1877 "type" : "string", 1878 "multiValued" : false, 1879 "description" : "An OPTIONAL JSON Web Key Set [RFC7517] that 1880 contains the Event Receiver's encryption keys that MAY be used 1881 by the Event Transmitter to encrypt SET tokens for the specified 1882 Event Receiver.", 1883 "required" : false, 1884 "caseExact" : false, 1885 "mutability" : "readWrite", 1886 "returned" : "default", 1887 "uniqueness" : "none" 1888 }, 1889 { 1890 "name" : "status", 1891 "type" : "string", 1892 "multiValued" : false, 1893 "description" : "An OPTIONAL JSON String keyword that indicates 1894 the current state of an Event Stream. More information on the E 1895 vent Stream state can be found in Section 2.3.", 1896 "required" : false, 1897 "caseExact" : false, 1898 "mutability" : "readWrite", 1899 "returned" : "default", 1900 "uniqueness" : "none", 1901 "canonicalValues" : [ 1902 "on", 1903 "off", 1904 "verify", 1905 "paused", 1906 "fail" 1907 ] 1908 }, 1909 { 1910 "name" : "maxRetries", 1911 "type" : "integer", 1912 "multiValued" : false, 1913 "description" : "An OPTIONAL JSON number indicating the maximum 1914 number of attempts to deliver a SET. A value of '0' indicates 1915 there is no maximum. Upon reaching the maximum, the Event Stream 1916 'status' attribute is set to 'failed'.", 1917 "required" : false, 1918 "mutability" : "readWrite", 1919 "returned" : "default", 1920 "uniqueness" : "none" 1921 }, 1922 { 1923 "name" : "maxDeliveryTime", 1924 "type" : "integer", 1925 "multiValued" : false, 1926 "description" : "An OPTIONAL number indicating the maximum 1927 amount of time in seconds a SET MAY take for successful delivery 1928 per request or cumulatively across multiple retries. Upon 1929 reaching the maximum, the Event Stream 'status' is set to 1930 'failed'. If undefined, there is no maximum time.", 1931 "required" : false, 1932 "mutability" : "readWrite", 1933 "returned" : "default", 1934 "uniqueness" : "none" 1936 }, 1937 { 1938 "name" : "minDeliveryInterval", 1939 "type" : "integer", 1940 "multiValued" : false, 1941 "description" : "An OPTIONAL JSON integer that represents the 1942 minimum interval in seconds between deliveries. A value of '0' 1943 indicates delivery should happen immediately. When delivery is 1944 a polling method (e.g. HTTP GET), it is the expected time 1945 between Event Receiver attempts. When in push mode (e.g. 1946 HTTP POST), it is the interval the server will wait before 1947 sending a new event or events.", 1948 "required" : false, 1949 "mutability" : "readWrite", 1950 "returned" : "default", 1951 "uniqueness" : "none" 1952 }, 1953 { 1954 "name" : "txErr", 1955 "type" : "string", 1956 "multiValued" : false, 1957 "description" : "An OPTIONAL JSON String keyword value. When 1958 the Event Stream has 'status' set to 'fail', a keyword condition 1959 is set.", 1960 "required" : false, 1961 "caseExact" : false, 1962 "mutability" : "readWrite", 1963 "returned" : "default", 1964 "uniqueness" : "none", 1965 "canonicalValues" : [ 1966 "connection", 1967 "tls", 1968 "dnsname", 1969 "receiver", 1970 "other" 1971 ] 1972 }, 1973 { 1974 "name" : "txErrDesc", 1975 "type" : "string", 1976 "multiValued" : false, 1977 "description" : "An OPTIONAL String value that is usually human 1978 readable that provides further diagnostic detail by the 1979 indicated 'txErr' error code.", 1980 "required" : false, 1981 "caseExact" : false, 1982 "mutability" : "readWrite", 1983 "returned" : "default", 1984 "uniqueness" : "none" 1985 }, 1986 { 1987 "name" : "verifyNonce", 1988 "type" : "string", 1989 "multiValued" : false, 1990 "description" : "An OPTIONAL String value that when changed 1991 or set by a Control Plane client will cause the Event Transmitter 1992 to issue a single Verify Event based on the value provided.", 1993 "required" : false, 1994 "caseExact" : false, 1995 "mutability" : "writeOnly", 1996 "returned" : "never", 1997 "uniqueness" : "none" 1998 }, 1999 { 2000 "name" : "subjects", 2001 "type" : "complex", 2002 "multiValued" : true, 2003 "description" : "An optional list of subjects that are part of 2004 the Stream.", 2005 "required" : false, 2006 "subAttributes" : [ 2007 { 2008 "name" : "value", 2009 "type" : "string", 2010 "multiValued" : false, 2011 "description" : "Identifier of the member of this Group. 2012 The contents of this parameter are determined by the value 2013 of the sub-attribute 'type'.", 2014 "required" : false, 2015 "caseExact" : false, 2016 "mutability" : "immutable", 2017 "returned" : "default", 2018 "uniqueness" : "none" 2019 }, 2020 { 2021 "name" : "type", 2022 "type" : "string", 2023 "multiValued" : false, 2024 "description" : "A label indicating the type of resource, 2025 e.g., OIDC Connect Subject, SAML Subject, Email address, 2026 Telephone Number, SCIM User or SCIM Group, or the URI 2027 of some other network addressable subject.", 2028 "required" : false, 2029 "caseExact" : false, 2030 "canonicalValues" : [ 2031 "User", 2032 "Group", 2033 "OIDC", 2034 "SAML" 2035 "EMIL", 2036 "PHONE", 2037 "URI" 2038 ], 2039 "mutability" : "immutable", 2040 "returned" : "default", 2041 "uniqueness" : "none" 2042 } 2043 ], 2044 "mutability" : "readWrite", 2045 "returned" : "request" 2046 } 2047 ], 2049 "meta" : { 2050 "resourceType" : "Schema", 2051 "location" : 2052 "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group" 2053 } 2054 }, 2056 Appendix B. Acknowledgments 2058 The editors would like to thanks the members of the SCIM WG which 2059 began discussions of provisioning events starting with: draft-hunt- 2060 scim-notify-00 in 2015. 2062 This draft is a re-work of material from Sections 2 and 4 of draft- 2063 hunt-secevent-distribution-01. The editor would like to thank Marius 2064 Scurtescu, Tony Nadalin, and Morteza Ansari for their contributions 2065 in previous drafts. 2067 The editor would like to thank the participants in the the SECEVENTS 2068 working group for their support of this specification. 2070 Appendix C. Change Log 2072 Draft 00 - PH - First Draft based on control plane portions of draft- 2073 hunt-idevent-distribution 2075 Author's Address 2076 Phil Hunt (editor) 2077 Oracle Corporation 2079 Email: phil.hunt@yahoo.com