idnits 2.17.1 draft-scurtescu-secevent-simple-control-plane-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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 29, 2017) is 2493 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7159 (ref. 'JSON') (Obsoleted by RFC 8259) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 secevent M. Scurtescu 3 Internet-Draft Google 4 Intended status: Informational A. Backman 5 Expires: December 31, 2017 Amazon 6 June 29, 2017 8 Management API for SET Event Streams 9 draft-scurtescu-secevent-simple-control-plane-00 11 Abstract 13 Security Event Token (SET) delivery requires event receivers to 14 indicate to event transmitters the subjects about which they wish to 15 receive events, and how they wish to receive them. This 16 specification defines an HTTP API for a basic control plane that 17 event transmitters can implement and event receivers may use to 18 manage the flow of events from one to the other. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on December 31, 2017. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 56 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 4. Event Stream Management . . . . . . . . . . . . . . . . . . . 4 58 4.1. Stream Configuration . . . . . . . . . . . . . . . . . . 4 59 4.1.1. Reading a Stream's Configuration . . . . . . . . . . 4 60 4.2. Subjects . . . . . . . . . . . . . . . . . . . . . . . . 5 61 4.2.1. Adding a Subject to a Stream . . . . . . . . . . . . 5 62 4.2.2. Removing a Subject . . . . . . . . . . . . . . . . . 7 63 4.3. Verification . . . . . . . . . . . . . . . . . . . . . . 8 64 4.3.1. Triggering a Verification Event. . . . . . . . . . . 8 65 5. Normative References . . . . . . . . . . . . . . . . . . . . 10 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 68 1. Introduction 70 This specification defines an HTTP API to be implemented by Event 71 Transmitters and that can be used by Event Receivers to query the 72 Event Stream status, to add and remove subjects and to trigger 73 verification. 75 +------------+ +------------+ 76 | | Stream Status | | 77 | Event <----------------+ Event | 78 | Stream | | Receiver | 79 | Management | Add Subject | | 80 | API <----------------+ | 81 | | | | 82 | | Remove Subject | | 83 | <----------------+ | 84 | | | | 85 | | Verification | | 86 | <----------------+ | 87 | | | | 88 +------------+ +------------+ 90 Figure 1: Event Stream Management API 92 How events are delivered and the structure of events are not in scope 93 for this specification. 95 2. Notational Conventions 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 99 document are to be interpreted as described in [RFC2119]. 101 3. Definitions 103 In addition to terms defined in [SET], this specification uses the 104 following terms: 106 Event Stream 107 An Event Stream is a configured relationship between a single 108 Event Transmitter and a single Event Receiver, describing one or 109 more methods by which the Event Transmitter may deliver SETs to 110 the Event Receiver. Event Streams are unidirectional, with only 111 one Event Transmitter and one Event Receiver. Event Transmitters 112 support only one Event Streams for a single Event Receiver. 114 Event Stream Management Endpoint 115 A URL hosted by the transmitter; it serves as the stream 116 management API for a stream. An Event Transmitter MAY use a 117 single Management Endpoint for multiple streams, provided that the 118 transmitter has some mechanism through which they can identify the 119 applicable stream for any given request, e.g. from authentication 120 credentials. The definition of such mechanisms is outside the 121 scope of this specification. 123 Add Subject Endpoint 124 A URL hosted by the transmitter used to add subjects to an Event 125 Stream. 127 Remove Subject Endpoint 128 A URL hosted by the transmitter used to remove subjects from an 129 Event Stream. 131 Verification Endpoint 132 A URL hosted by the transmitter used to trigger a Verification 133 Event to be sent to the receiver. 135 Event Stream Management API 136 The API collectively made up by the four endpoints defined above. 138 Subject Identifier Object 139 A JSON object containing a set of one or more claims about a 140 subject that when taken together uniquely identify that subject. 141 This set of claims SHOULD be declared as an acceptable way to 142 identify subjects of SETs by one or more specifications that 143 profile [SET]. 145 Verification Event 146 A special event type for testing Event Streams. Receivers can 147 request such an event through the Verification Endpoint. 148 Transmitters can periodically send these events to ensure the 149 connection is alive. 151 4. Event Stream Management 153 Event Receivers manage how they receive events, and the subjects 154 about which they want to receive events over an Event Stream by 155 making HTTP requests to endpoints in the Event Stream Management API. 157 4.1. Stream Configuration 159 An Event Stream's configuration is represented as a JSON object with 160 the following properties: 162 aud 163 A string containing an audience claim as defined in JSON Web Token 164 (JWT) [RFC7519] that identifies the Event Receiver for the Event 165 Stream. 167 events 168 OPTIONAL. An array of URIs identifying the set of events which 169 MAY be delivered over the Event Stream. If omitted, Event 170 Transmitters SHOULD make this set available to the Event Receiver 171 via some other means (e.g. publishing it in online 172 documentation). 174 delivery 175 A JSON object containing a set of name/value pairs specifying 176 configuration parameters for the SET delivery method. The actual 177 delivery method is identified by the special key "delivery_method" 178 with the value being a URI as defined in [DELIVERY]. 180 4.1.1. Reading a Stream's Configuration 182 An Event Receiver gets the current configuration of a stream by 183 making an HTTP GET request to the Event Stream Management Endpoint. 184 On receiving a valid request the Event Transmitter responds with a 185 200 OK response containing a [JSON] representation of the stream's 186 configuration in the body. 188 The following is a non-normative example request to read an Event 189 Stream's configuration: 191 GET /set/stream HTTP/1.1 192 Host: transmitter.example.com 193 Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= 195 Figure 2: Example: Stream Status Request 197 The following is a non-normative example response: 199 HTTP/1.1 200 OK 200 Content-Type: application/json; charset=UTF-8 201 Cache-Control: no-store 202 Pragma: no-cache 204 { 205 "aud": "http://www.example.com", 206 "delivery": { 207 "delivery_method": "https://schemas.example.com/set/http-push", 208 "url": "https://receiver.example.com/events" 209 }, 210 "events": [ 211 "https://schemas.openid.net/risc/event-type/account-at-risk", 212 "https://schemas.openid.net/risc/event-type/account-deleted", 213 "https://schemas.openid.net/risc/event-type/account-locked", 214 "https://schemas.openid.net/risc/event-type/account-unlocked", 215 "https://schemas.openid.net/risc/event-type/client-credentials- 216 revoked", 217 "https://schemas.openid.net/risc/event-type/sessions-revoked", 218 "https://schemas.openid.net/risc/event-type/tokens-revoked" 219 ] 220 } 222 Figure 3: Example: Stream Status Response 224 4.2. Subjects 226 An Event Receiver can indicate to an Event Transmitter whether or not 227 the receiver wants to receive events about a particular subject by 228 "adding" or "removing" that subject to the Event Stream, 229 respectively. 231 4.2.1. Adding a Subject to a Stream 233 To add a subject to an Event Stream, the Event Receiver makes an HTTP 234 POST request to the Add Subject Endpoint, containing in the body a 235 Subject Identifier Object identifying the subject to be added. On a 236 successful response, the Event Transmitter responds with an empty 200 237 OK response. 239 The Event Transmitter MAY choose to silently ignore the request, for 240 example if the subject has previously indicated to the transmitter 241 that they do not want events to be transmitted to the Event Receiver. 242 In this case, the transmitter MUST return an empty 200 OK response, 243 and MUST NOT indicate to the receiver that the request was ignored. 245 Errors are signaled with HTTP staus codes as follows: 247 +------+------------------------------------------------------------+ 248 | Code | Description | 249 +------+------------------------------------------------------------+ 250 | 400 | if the request body cannot be parsed or if the request is | 251 | | otherwise invalid | 252 | | | 253 | 401 | if authorization failed or it is missing | 254 | | | 255 | 403 | if the Event Receiver is not allowed to add this | 256 | | particular subject | 257 | | | 258 | 404 | if the subject is not recognized by the Event Transmitter, | 259 | | the Event Transmitter may chose to stay silent in this | 260 | | case and responde with 200 | 261 | | | 262 | 429 | if the Event Receiver is sending too many requests in a | 263 | | gvien amount of time | 264 +------+------------------------------------------------------------+ 266 Table 1: Add Subject Errors 268 The following is a non-normative example request to add a subject to 269 a stream, where the subject is identified by an OpenID Connect email 270 claim: 272 POST /set/subjects:add HTTP/1.1 273 Host: transmitter.example.com 274 Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= 276 { 277 "email": "example.user@example.com" 278 } 280 Figure 4: Example: Add Subject Request 282 The following is a non-normative example response to a successful 283 request: 285 HTTP/1.1 200 OK 286 Server: transmitter.example.com 287 Cache-Control: no-store 288 Pragma: no-cache 290 Figure 5: Example: Add Subject Response 292 4.2.2. Removing a Subject 294 To remove a subject from an Event Stream, the Event Receiver makes an 295 HTTP POST request to the Remove Subject Endpoint, containing in the 296 body a Subject Identifier Object identifying the subject to be 297 removed. On a successful response, the Event Transmitter responds 298 with a 204 No Content response. 300 Errors are signaled with HTTP staus codes as follows: 302 +------+------------------------------------------------------------+ 303 | Code | Description | 304 +------+------------------------------------------------------------+ 305 | 400 | if the request body cannot be parsed or if the request is | 306 | | otherwise invalid | 307 | | | 308 | 401 | if authorization failed or it is missing | 309 | | | 310 | 403 | if the Event Receiver is not allowed to remove this | 311 | | particular subject | 312 | | | 313 | 404 | if the subject is not recognized by the Event Transmitter, | 314 | | the Event Transmitter may chose to stay silent in this | 315 | | case and responde with 204 | 316 | | | 317 | 429 | if the Event Receiver is sending too many requests in a | 318 | | gvien amount of time | 319 +------+------------------------------------------------------------+ 321 Table 2: Remove Subject Errors 323 The following is a non-normative example request where the subject is 324 identified by a phone_number claim: 326 POST /set/subjects:remove HTTP/1.1 327 Host: transmitter.example.com 328 Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= 330 { 331 "phone_number": "123-456-7890" 332 } 334 Figure 6: Example: Remove Subject Request 336 The following is a non-normative example response to a successful 337 request: 339 HTTP/1.1 204 No Content 340 Server: transmitter.example.com 341 Cache-Control: no-store 342 Pragma: no-cache 344 Figure 7: Example: Remove Subject Response 346 4.3. Verification 348 In some cases, the frequency of event transmission on an Event Stream 349 will be very low, making it difficult for an Event Receiver to tell 350 the difference between expected behavior and event transmission 351 failure due to a misconfigured stream. Event Receivers can request 352 that a verification event be transmitted over the Event Stream, 353 allowing the receiver to confirm that the stream is configured 354 correctly upon successful receipt of the event. 356 Verification requests have the following properties: 358 state 359 OPTIONAL. An arbitrary string that the Event Transmitter MUST 360 echo back to the Event Receiver in the verification event's 361 payload. Event Receivers MAY use the value of this parameter to 362 correlate a verification event with a verification request. 364 4.3.1. Triggering a Verification Event. 366 To request that a verification event be sent over an Event Stream, 367 the Event Receiver makes an HTTP POST request to the Verification 368 Endpoint, with a JSON object containing the parameters of the 369 verification request, if any. On a successful request, the event 370 transmitter responds with an empty 204 No Content response. 372 A successful response from a POST to the Verification Endpoint does 373 not indicate that the verification event was transmitted 374 successfully, only that the Event Transmitter has transmitted the 375 event or will do so at some point in the future. Event Transmitters 376 MAY transmit the event via an asynchronous process, and SHOULD 377 publish an SLA for verification event transmission times. Event 378 Receivers MUST NOT depend on the verification event being transmitted 379 synchronously with their request. 381 Errors are signaled with HTTP staus codes as follows: 383 +------+------------------------------------------------------------+ 384 | Code | Description | 385 +------+------------------------------------------------------------+ 386 | 400 | if the request body cannot be parsed or if the request is | 387 | | otherwise invalid | 388 | | | 389 | 401 | if authorization failed or it is missing | 390 | | | 391 | 429 | if the Event Receiver is sending too many requests in a | 392 | | gvien amount of time | 393 +------+------------------------------------------------------------+ 395 Table 3: Verification Errors 397 The following is a non-normative example request to trigger a 398 verification event: 400 POST /set/verify HTTP/1.1 401 Host: transmitter.example.com 402 Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= 403 Content-Type: application/json; charset=UTF-8 405 { 406 "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo=" 407 } 409 Figure 8: Example: Trigger Verification Request 411 The following is a non-normative example response to a successful 412 request: 414 HTTP/1.1 204 No Content 415 Server: transmitter.example.com 416 Cache-Control: no-store 417 Pragma: no-cache 419 Figure 9: Example: Trigger Verification Response 421 And the following is a non-normative example of a verification event 422 sent to the Event Receiver as a result of the above request: 424 { 425 "jti": "123456", 426 "iss": "https://transmitter.example.com", 427 "aud": "receiver.example.com", 428 "iat": "1493856000", 429 "events": [ 430 "urn:ietf:params:secevent:event-type:core:verify" : { 431 "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo=", 432 }, 433 ], 434 } 436 Figure 10: Example: Verification SET 438 5. Normative References 440 [DELIVERY] 441 "SET Token Delivery Using HTTP", n.d., . 445 [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 446 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 447 2014, . 449 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 450 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 451 RFC2119, March 1997, 452 . 454 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 455 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 456 . 458 [SET] "Security Event Token (SET)", n.d., . 461 Authors' Addresses 463 Marius Scurtescu 464 Google 466 Email: mscurtescu@google.com 467 Annabelle Backman 468 Amazon 470 Email: richanna@amazon.com