Movatterモバイル変換

RFC 8936	Poll-Based SET Delivery Using HTTP	November 2020
Backman, et al.	Standards Track	[Page]

2.SET Delivery

When a SET is available for a SET Recipient, the SET Transmitter queues the SET in a buffer so that a SET Recipient can poll for SETs using HTTP POST.¶

In poll-based SET delivery using HTTP over TLS, zero or more SETs are delivered in a JSON[RFC8259] document to a SET Recipient in response to an HTTP POST request to the SET Transmitter. Then in a following request, the SET Recipient acknowledges received SETs and can poll for more. All requests and responses are JSON documents and use aContent-Type ofapplication/json, as described inSection 2.2.¶

After successful (acknowledged) SET delivery, SET Transmitters are not required to retain or record SETs for retransmission. Once a SET is acknowledged, the SET RecipientSHALL be responsible for retention, if needed. Transmitters may also discard undelivered SETs under deployment-specific conditions, such as if they have not been polled for over too long a period of time or if an excessive amount of storage is needed to retain them.¶

Upon receiving a SET, the SET Recipient reads the SET and validates it in the manner described inSection 2 of [RFC8935]. The SET RecipientMUST acknowledge receipt to the SET Transmitter, andSHOULD do so in a timely fashion, as described inSection 2.4. The SET RecipientSHALL NOT use the event acknowledgement mechanism to report event errors other than those relating to the parsing and validation of the SET.¶

2.1.Polling Delivery using HTTP

This method allows a SET Recipient to use HTTP POST (Section 4.3.3 of [RFC7231]) to acknowledge SETs and to check for and receive zero or more SETs. RequestsMAY be made at a periodic interval (short polling) or requestsMAY wait, pending availability of new SETs using long polling, perSection 2 of [RFC6202]. Note that short polling will result in retrieving zero or more SETs whereas long polling will typically result in retrieving one or more SETs unless a timeout occurs.¶

The delivery of SETs in this method is facilitated by HTTP POST requests initiated by the SET Recipient in which:¶

The SET Recipient makes a request for available SETs using an HTTP POST to a pre-arranged endpoint provided by the SET Transmitter, or¶
after validating previously received SETs, the SET Recipient initiates another poll request using HTTP POST that includes acknowledgement of previous SETs and requests the next batch of SETs.¶

The purpose of the acknowledgement is to inform the SET Transmitter that delivery has succeeded and redelivery is no longer required. Before acknowledgement, SET Recipients validate the received SETs and retain them in a manner appropriate to the recipient's requirements. The level and method of retention of SETs by SET Recipients is out of scope of this specification.¶

2.2.Polling HTTP Request

When initiating a poll request, the SET Recipient constructs a JSON document that consists of polling request parameters and SET acknowledgement parameters in the form of JSON objects.¶

When making a request, the HTTPContent-Type header field is set toapplication/json.¶

The following JSON object members are used in a polling request:¶

Request Processing Parameters

maxEvents: AnOPTIONAL integer value indicating the maximum number of unacknowledged SETs to be returned. The SET TransmitterSHOULD NOT send more SETs than the specified maximum. If more than the maximum number of SETs are available, the SET Transmitter determines which to return first; the oldest SETs availableMAY be returned first, or another selection algorithmMAY be used, such as prioritizing SETs in some manner that makes sense for the use case. A value of0MAY be used by SET Recipients that would like to perform an acknowledge-only request. This enables the Recipient to use separate HTTP requests for acknowledgement and reception of SETs. If this parameter is omitted, no limit is placed on the number of SETs to be returned.¶
returnImmediately: AnOPTIONAL JSON boolean value that indicates the SET TransmitterSHOULD return an immediate response even if no results are available (short polling). The default value isfalse, which indicates the request is to be treated as an HTTP long poll, perSection 2 of [RFC6202]. The timeout for the request is part of the configuration between the participants, which is out of scope of this specification.¶

SET Acknowledgment Parameters

ack: A JSON array of strings whose values are thejti[RFC7519] values of successfully received SETs that are being acknowledged. If there are no outstanding SETs to acknowledge, this member is omitted or contains an empty array. Once a SET has been acknowledged, the SET Transmitter is released from any obligation to retain the SET.¶
setErrs: A JSON object with one or more members whose keys are thejti values of invalid SETs received. The values of these objects are themselves JSON objects that describe the errors detected using theerr anddescription values specified inSection 2.6. If there are no outstanding SETs with errors to report, this member is omitted or contains an empty JSON object.¶

2.3.Polling HTTP Response

In response to a poll request, the SET Transmitter checks for available SETs and responds with a JSON document containing the following JSON object members:¶

sets: A JSON object containing zero or more SETs being returned. Each member name is thejti of a SET to be delivered, and its value is a JSON string representing the corresponding SET. If there are no outstanding SETs to be transmitted, the JSON objectSHALL be empty. Note that both SETs being transmitted for the first time and SETs that are being retransmitted after not having been acknowledged are communicated here.¶
moreAvailable: A JSON boolean value that indicates if more unacknowledged SETs are available to be returned. This memberMAY be omitted, with the meaning being the same as including it with the boolean valuefalse.¶

When making a response, the HTTPContent-Type header field is set toapplication/json.¶

2.4.Poll Request

The SET Recipient performs an HTTP POST (seeSection 4.3.4 of [RFC7231]) to a pre-arranged polling endpoint URI to check for SETs that are available. Because the SET Recipient has no prior SETs to acknowledge, theack andsetErrs request parameters are omitted.¶

After a period of time configured in an out-of-band manner between the SET Transmitter and Recipient, a SET TransmitterMAY redeliver SETs it has previously delivered. The SET RecipientSHOULD accept repeat SETs and acknowledge the SETs regardless of whether the Recipient believes it has already acknowledged the SETs previously. A SET TransmitterMAY limit the number of times it attempts to deliver a SET.¶

If the SET Recipient has received SETs from the SET Transmitter, the SET Recipient parses and validates that received SETs meet its own requirements andSHOULD acknowledge receipt in a timely fashion (e.g., seconds or minutes) so that the SET Transmitter can mark the SETs as received. SET RecipientsSHOULD acknowledge receipt before taking any local actions based on the SETs to avoid unnecessary delay in acknowledgement, where possible.¶

Poll requests have three variations:

Poll-Only: In this scenario, a SET Recipient asks for the next set of events where no previous SET deliveries are acknowledged (such as in the initial poll request).¶
Acknowledge-Only: In this scenario, a SET Recipient sets themaxEvents value to0 along withack andsetErrs members indicating the SET Recipient is acknowledging previously received SETs and does not want to receive any new SETs in response to the request.¶
Combined Acknowledge and Poll: In this scenario, a SET Recipient is both acknowledging previously received SETs using theack andsetErrs members and will wait for the next group of SETs in the SET Transmitters response.¶

2.4.1.Poll-Only Request

In the case where no SETs were received in a previous poll (seeFigure 7), the SET Recipient simply polls without acknowledgement parameters (ack andsetErrs).¶

The following is a non-normative example request made by a SET Recipient that has no outstanding SETs to acknowledge and is polling for available SETs at the endpointhttps://notify.idp.example.com/Events:¶

  POST /Events HTTP/1.1  Host: notify.idp.example.com  Content-Type: application/json  {   "returnImmediately": true  }

Figure 1:Example Initial Poll Request

A SET Recipient can poll using default parameter values by passing an empty JSON object.¶

The following is a non-normative example default poll request to the endpointhttps://notify.idp.example.com/Events:¶

  POST /Events HTTP/1.1  Host: notify.idp.example.com  Content-Type: application/json  {}

Figure 2:Example Default Poll Request

2.4.2.Acknowledge-Only Request

In this variation, the SET Recipient acknowledges previously received SETs and indicates it does not want to receive SETs in response by setting themaxEvents value to0. This variation might be used, for instance, when a SET Recipient needs to acknowledge received SETs independently (e.g., on separate threads) from the process of receiving SETs.¶

If the poll needs to return immediately, thenreturnImmediatelyMUST also be present with the valuetrue. If it isfalse, then a long poll will still occur until an event is ready to be returned, even though no events will be returned.¶

The following is a non-normative example poll request with acknowledgement of SETs received (for example, as shown inFigure 6):¶

  POST /Events HTTP/1.1  Host: notify.idp.example.com  Content-Type: application/json  {    "ack": [      "4d3559ec67504aaba65d40b0363faad8",      "3d0c3cf797584bd193bd0fb1bd4e7d30"    ],    "maxEvents": 0,    "returnImmediately": true  }

Figure 3:Example Acknowledge-Only Request

2.4.3.Poll with Acknowledgement

This variation allows a recipient thread to simultaneously acknowledge previously received SETs and wait for the next group of SETs in a single request.¶

The following is a non-normative example poll with acknowledgement of the SETs received inFigure 6:¶

  POST /Events HTTP/1.1  Host: notify.idp.example.com  Content-Type: application/json  {    "ack": [      "4d3559ec67504aaba65d40b0363faad8",      "3d0c3cf797584bd193bd0fb1bd4e7d30"    ],    "returnImmediately": false  }

Figure 4:Example Poll with Acknowledgement and No Errors

In the above acknowledgement, the SET Recipient has acknowledged receipt of two SETs and has indicated it wants to wait until the next SET is available.¶

2.4.4.Poll with Acknowledgement and Errors

In the case where errors were detected in previously delivered SETs, the SET RecipientMAY use thesetErrs member to communicate the errors in the following poll request.¶

The following is a non-normative example of a response acknowledging one successfully received SET and one SET with an error from the two SETs received inFigure 6:¶

  POST /Events HTTP/1.1  Host: notify.idp.example.com  Content-Language: en-US  Content-Type: application/json  {    "ack": ["3d0c3cf797584bd193bd0fb1bd4e7d30"],    "setErrs": {      "4d3559ec67504aaba65d40b0363faad8": {        "err": "authentication_failed",        "description": "The SET could not be authenticated"      }    },    "returnImmediately": true  }

Figure 5:Example Poll Acknowledgement with Error

2.5.Poll Response

In response to a valid poll request, the service providerMAY respond immediately if SETs are available to be delivered. If no SETs are available at the time of the request, the SET TransmitterSHALL delay responding until a SET is available or the timeout interval has elapsed unless the poll request parameterreturnImmediately is present with the valuetrue.¶

As described inSection 2.3, a JSON document is returned containing members includingsets, whichSHALL contain zero or more SETs.¶

The following is a non-normative example response to the request shown inSection 2.4. This example shows two SETs being returned:¶

HTTP/1.1 200 OKContent-Type: application/json{ "sets":  {   "4d3559ec67504aaba65d40b0363faad8":   "eyJhbGciOiJub25lIn0.    eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdC    I6MTQ1ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwi    YXVkIjpbImh0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MW    ZhNWJiYzg3OTU5M2I3NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0Zl    ZWRzLzVkNzYwNDUxNmIxZDA4NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybj    ppZXRmOnBhcmFtczpzY2ltOmV2ZW50OmNyZWF0ZSI6eyJyZWYiOiJodHRwczov    L3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZhYjYxZTc1Mj    FkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuYW1lIiwidXNlck5hbWUiLCJwYXNz    d29yZCIsImVtYWlscyJdfX19.",   "3d0c3cf797584bd193bd0fb1bd4e7d30":   "eyJhbGciOiJub25lIn0.    eyJqdGkiOiIzZDBjM2NmNzk3NTg0YmQxOTNiZDBmYjFiZDRlN2QzMCIsImlhdC    I6MTQ1ODQ5NjAyNSwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwi    YXVkIjpbImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MW    ZhNWJiYzg3OTU5M2I3NzU0IiwiaHR0cHM6Ly9qaHViLmV4YW1wbGUuY29tL0Zl    ZWRzLzVkNzYwNDUxNmIxZDA4NjQxZDc2NzZlZTciXSwic3ViIjoiaHR0cHM6Ly    9zY2ltLmV4YW1wbGUuY29tL1VzZXJzLzQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIx    ZDkiLCJldmVudHMiOnsidXJuOmlldGY6cGFyYW1zOnNjaW06ZXZlbnQ6cGFzc3    dvcmRSZXNldCI6eyJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkifSwi    aHR0cHM6Ly9leGFtcGxlLmNvbS9zY2ltL2V2ZW50L3Bhc3N3b3JkUmVzZXRFeH    QiOnsicmVzZXRBdHRlbXB0cyI6NX19fQ."  }}

Figure 6:Example Poll Response

In the above example, two SETs whosejti values are4d3559ec67504aaba65d40b0363faad8 and3d0c3cf797584bd193bd0fb1bd4e7d30 are delivered.¶

The following is a non-normative example response to the request shown inSection 2.4.1, which indicates that no new SETs or unacknowledged SETs are available:¶

  HTTP/1.1 200 OK  Content-Type: application/json  {   "sets": {}  }

Figure 7:Example No SETs Poll Response

Upon receiving the JSON document (e.g., as shown inFigure 6), the SET Recipient parses and verifies the received SETs and notifies the SET Transmitter of successfully received SETs and SETs with errors via the next poll request to the SET Transmitter, as described in Sections2.4.3 and2.4.4.¶

2.5.1.Poll Error Response

In the event of a general HTTP error condition in the context of processing a poll request, the service provider responds with the applicable HTTP response status code, as defined inSection 6 of [RFC7231].¶

Service providersMAY respond to any invalid poll request with an HTTP response status code of 400 (Bad Request) even when a more specific code might apply, for example, if the service provider deemed that a more specific code presented an information disclosure risk. When no more specific code might apply, the service providerSHALL respond to an invalid poll request with an HTTP status code of 400.¶

The response body for responses to invalid poll requests is left undefined, and its contentsSHOULD be ignored.¶

The following is a non-normative example of a response to an invalid poll request:¶

  HTTP/1.1 400 Bad Request

Figure 8:Example Poll Error Response

2.6.Error Response Handling

If a SET is invalid, error codes from the IANA "Security Event Token Error Codes" registry established by[RFC8935] are used in error responses. As described inSection 2.3 of [RFC8935], an error response is a JSON object providing details about the error that includes the following name/value pairs:¶

err:: A value from the IANA "Security Event Token Error Codes" registry that identifies the error.¶
description:: A human-readable string that provides additional diagnostic information.¶

When included as part of a batch of SETs, the above JSON is included as part of thesetErrs member, as defined in Sections2.2 and2.4.4.¶

When the SET Recipient includes one or more error responses in a request to the SET Transmitter, it must also include in the request aContent-Language header field whose value indicates the language of the error descriptions included in the request. The method of language selection in the case when the SET Recipient can provide error messages in multiple languages is out of scope for this specification.¶

Movatterモバイル変換

RFC 8936

Poll-Based Security Event Token (SET) Delivery Using HTTP

Abstract

Status of This Memo

Copyright Notice

Table of Contents

1.Introduction and Overview

1.1.Notational Conventions

1.2.Definitions

2.SET Delivery

2.1.Polling Delivery using HTTP

2.2.Polling HTTP Request

2.3.Polling HTTP Response

2.4.Poll Request

2.4.1.Poll-Only Request

2.4.2.Acknowledge-Only Request

2.4.3.Poll with Acknowledgement

2.4.4.Poll with Acknowledgement and Errors

2.5.Poll Response

2.5.1.Poll Error Response

2.6.Error Response Handling

3.Authentication and Authorization

4.Security Considerations

4.1.Authentication Using Signed SETs

4.2.HTTP Considerations

4.3.Confidentiality of SETs

4.4.Access Token Considerations

4.4.1.Bearer Token Considerations

5.Privacy Considerations

6.IANA Considerations

7.References

7.1.Normative References

7.2.Informative References

Appendix A.Unencrypted Transport Considerations

Acknowledgments

Authors' Addresses