A. Tulshibagwale Google T. Cappalli Microsoft M. Scurtescu Coinbase A. Backman Amazon J. Bradley Yubico June 8, 2021 OpenID Shared Signals and Events Framework Specification 1.0 - draft 01 openid-sse-framework-1_0 Abstract This Shared Signals and Events (SSE) Framework enables sharing of signals and events between cooperating peers. It enables multiple applications such as Risk Incident Sharing and Coordination (RISC) and the Continuous Access Evaluation Profile ([CAEP]) This specification defines: o A profile for IETF Security Events [1] o Subject Principals o Subject Claims in SSE Events o Event Types o Event Properties o Configuration information and discovery method for Transmitters o A Management API for Event Streams This spec also directly profiles several IETF Security Events drafts: o Security Event Token (SET) [SET] o Subject Identifiers for Security Event Tokens [SUBIDS] o Push-Based SET Token Delivery Using HTTP [DELIVERYPUSH] o Poll-Based SET Token Delivery Using HTTP [DELIVERYPOLL] Tulshibagwale, et al. Expires December 10, 2021 [Page 1] openid-sse-framework June 2021 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 2. Subject Principals . . . . . . . . . . . . . . . . . . . . . 3 3. Subject Members in SSE Events . . . . . . . . . . . . . . . . 4 3.1. Simple Subject Members . . . . . . . . . . . . . . . . . 4 3.2. Complex Subject Members . . . . . . . . . . . . . . . . . 4 3.2.1. Complex Subject Interpretation . . . . . . . . . . . 5 3.3. Subject Identifiers in SSE Events . . . . . . . . . . . . 5 3.4. Additional Subject Identifier Formats . . . . . . . . . . 6 3.4.1. JWT ID Subject Identifier Format . . . . . . . . . . 6 3.4.2. SAML Assertion ID Subject Identifier Format . . . . . 6 3.5. Receiver Subject Processing . . . . . . . . . . . . . . . 7 4. Event Properties . . . . . . . . . . . . . . . . . . . . . . 7 5. Example SETs that conform to the SSE framework . . . . . . . 7 6. Transmitter Configuration Discovery . . . . . . . . . . . . . 10 6.1. Transmitter Configuration Metadata . . . . . . . . . . . 10 6.2. Obtaining Transmitter Configuration Information . . . . . 10 6.2.1. Transmitter Configuration Request . . . . . . . . . . 11 6.2.2. Transmitter Configuration Response . . . . . . . . . 11 6.2.3. Transmitter Configuration Validation . . . . . . . . 12 7. Management API for SET Event Streams . . . . . . . . . . . . 13 7.1. Event Stream Management . . . . . . . . . . . . . . . . . 13 7.1.1. Stream Status . . . . . . . . . . . . . . . . . . . . 15 7.1.1.1. Reading a Stream's Status . . . . . . . . . . . . 15 7.1.1.2. Updating a Stream's Status . . . . . . . . . . . 17 7.1.2. Stream Configuration . . . . . . . . . . . . . . . . 19 7.1.2.1. Reading a Stream's Configuration . . . . . . . . 21 7.1.2.2. Updating a Stream's Configuration . . . . . . . . 23 7.1.2.3. Removing a Stream Configuration . . . . . . . . . 26 7.1.3. Subjects . . . . . . . . . . . . . . . . . . . . . . 27 7.1.3.1. Adding a Subject to a Stream . . . . . . . . . . 27 7.1.3.2. Removing a Subject . . . . . . . . . . . . . . . 29 7.1.4. Verification . . . . . . . . . . . . . . . . . . . . 30 7.1.4.1. Verification Event . . . . . . . . . . . . . . . 30 7.1.4.2. Triggering a Verification Event. . . . . . . . . 31 7.1.5. Stream Updated Event . . . . . . . . . . . . . . . . 33 8. Authorization . . . . . . . . . . . . . . . . . . . . . . . . 34 9. Security Considerations . . . . . . . . . . . . . . . . . . . 34 9.1. Subject Probing . . . . . . . . . . . . . . . . . . . . . 34 9.2. Information Harvesting . . . . . . . . . . . . . . . . . 35 9.3. Malicious Subject Removal . . . . . . . . . . . . . . . . 35 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 35 10.1. Subject Information Leakage . . . . . . . . . . . . . . 35 10.2. Previously Consented Data . . . . . . . . . . . . . . . 36 10.3. New Data . . . . . . . . . . . . . . . . . . . . . . . . 36 10.3.1. Organizational Data . . . . . . . . . . . . . . . . 36 Tulshibagwale, et al. Expires December 10, 2021 [Page 2] openid-sse-framework June 2021 10.3.2. Consentable Data . . . . . . . . . . . . . . . . . . 36 11. Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . 36 11.1. Security Event Token Profile . . . . . . . . . . . . . . 37 11.1.1. Signature Key Resolution . . . . . . . . . . . . . . 37 11.1.2. SSE Event Subject . . . . . . . . . . . . . . . . . 37 11.1.3. SSE Event Properties . . . . . . . . . . . . . . . . 37 11.1.4. Explicit Typing of SETs . . . . . . . . . . . . . . 38 11.1.5. The "exp" Claim . . . . . . . . . . . . . . . . . . 38 11.1.6. The "aud" Claim . . . . . . . . . . . . . . . . . . 38 11.1.7. The "events" claim . . . . . . . . . . . . . . . . . 39 11.1.8. Security Considerations . . . . . . . . . . . . . . 39 11.1.8.1. Distinguishing SETs from other Kinds of JWTs . . 39 11.2. SET Token Delivery Using HTTP Profile . . . . . . . . . 40 11.2.1. Stream Configuration Metadata . . . . . . . . . . . 40 11.2.1.1. Push Delivery using HTTP . . . . . . . . . . . . 40 11.2.1.2. Polling Delivery using HTTP . . . . . . . . . . 40 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 13.1. Normative References . . . . . . . . . . . . . . . . . . 41 13.2. Non-Normative References . . . . . . . . . . . . . . . . 42 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 43 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . 43 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 1. Introduction 1.1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. Subject Principals This SSE Framework specification defines a Subject Principal to be the entities about which an event can be sent by Transmitters and received by Receivers using the SSE Framework. Subject Principals are the managed entities in a SSE Transmitter or Receiver. These include human or robotic principals, devices, customer tenants in a multi-tenanted service, organizational units within a tenant, groups of subject principals or other entities that are managed by Transmitters and Receivers. There may be other actors or resources that can be treated as Subject Principals, and event- Tulshibagwale, et al. Expires December 10, 2021 [Page 3] openid-sse-framework June 2021 type definitions SHOULD specify the range of principals addressed by the event. Subject Principals are identified by Subject Members defined below. 3. Subject Members in SSE Events A member of type Subject in an SSE event MAY have any claim name. Each Subject Member MUST refer to exactly one Subject Principal. A Subject may be a "simple subject" or a "complex subject." 3.1. Simple Subject Members A Simple Subject Member has a claim name and a value that is a "Subject Identifier" as defined in the Subject Identifiers for Security Event Tokens [SUBIDS]. Below is a non-normative example of a Simple Subject Member in a SSE event. "transferer": { "format": "email", "email": "foo@example.com" } Figure 1: Example: Simple Subject 3.2. Complex Subject Members A Complex Subject Member has a name and a value that is a JSON [RFC7159] object that has one or more Simple Subject Members. The name of each Simple Subject Member in this value MAY be one of the following: user OPTIONAL. A Subject Identifier that identifies a user. device OPTIONAL. A Subject Identifier that identifies a device. session OPTIONAL. A Subject Identifier that identifies a session. application OPTIONAL. A Subject Identifier that identifies an application. tenant OPTIONAL. A Subject Identifier that identifies a tenant. Tulshibagwale, et al. Expires December 10, 2021 [Page 4] openid-sse-framework June 2021 org_unit OPTIONAL. A Subject Identifier that identifies an organizational unit. group OPTIONAL. A Subject Identifier that identifies a group. Additional Subject Member names MAY be used in Complex Subjects. Each member name MAY appear at most once in the Complex Subject value. Below is a non-normative example of a Complex Subject claim in a SSE event. "transferee": { "user" : { "format": "email", "email": "bar@example.com" }, "tenant" : { "format": "iss_sub", "iss" : "http://example.com/idp1", "sub" : "1234" } } Figure 2: Example: Complex Subject 3.2.1. Complex Subject Interpretation All members within a Complex Subject MUST represent attributes of the same Subject Principal. As a whole, the Complex Subject MUST refer to exactly one Subject Principal. 3.3. Subject Identifiers in SSE Events A Subject Identifier in a SSE event MUST have an identifier format that is any one of: o Defined in the IANA Registry defined in Subject Identifiers for Security Event Tokens [SUBIDS], located at ""https://www.iana.org/assignments/secevent/"." o An identifier format defined in the Additional Subject Identifier Formats (Section 3.4) section below, OR o A proprietary subject identifier format that is agreed to between parties. Members within a subject identifier that has a Tulshibagwale, et al. Expires December 10, 2021 [Page 5] openid-sse-framework June 2021 proprietary subject identifier format are agreed to between the parties and such agreement is outside the scope of this specification. 3.4. Additional Subject Identifier Formats The following new subject identifier formats are defined: 3.4.1. JWT ID Subject Identifier Format The "JWT ID" Subject Identifier Format specifies a JSON Web Token (JWT) identifier, defined in [RFC7519]. Subject Identifiers of this type MUST contain the following members: iss REQUIRED. The "iss" (issuer) claim of the JWT being identified, defined in [RFC7519] jti REQUIRED. The "jti" (JWT token ID) claim of the JWT being identified, defined in [RFC7519] The "JWT ID" Subject Identifier Format is identified by the name "jwt-id". Below is a non-normative example of Subject Identifier for the "jwt- id" Subject Identifier Format. { "format": "jwt-id", "iss": "https://idp.example.com/123456789/", "jti": "B70BA622-9515-4353-A866-823539EECBC8" } Figure 3: Example: 'jwt-id' Subject Identifier 3.4.2. SAML Assertion ID Subject Identifier Format The "SAML Assertion ID" Subject Identifier Format specifies a SAML 2.0 [OASIS.saml-core-2.0-os] assertion identifier. Subject Identifiers of this format MUST contain the following members: issuer REQUIRED. The "Issuer" value of the SAML assertion being identified, defined in [OASIS.saml-core-2.0-os] assertion_id Tulshibagwale, et al. Expires December 10, 2021 [Page 6] openid-sse-framework June 2021 REQUIRED. The "ID" value of the SAML assertion being identified, defined in [OASIS.saml-core-2.0-os] The "SAML Assertion ID" Subject Identifier Format is identified by the name "saml-assertion-id". Below is a non-normative example Subject Identifier for the "saml- assertion-id" Subject Identifier Format. { "format": "saml-assertion-id", "issuer": "https://idp.example.com/123456789/", "assertion_id": "_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6" } Figure 4: Example: 'saml-assertion-id' Subject Identifier 3.5. Receiver Subject Processing A SSE Receiver MUST make a best effort process all members from a Subject in an SSE event. The Transmitter Configuration Metadata (Section 6.1) defined below MAY define certain members within a Complex Subject to be Critical. A SSE Receiver MUST discard any event that contains a Subject with a Critical member that it is unable to process. 4. Event Properties Additional members about an event may be included in the "events" claim. Some of these members are required and specified as such in the respective event types specs. If a Transmitter determines that it needs to include additional members that are not specified in the event types spec, then the name of such members MUST be a URI. The discoverability of all additional members is specified in the Discovery (Section 6) section. 5. Example SETs that conform to the SSE framework The following are hypothetical examples of SETs that conform to the SSE framework. Tulshibagwale, et al. Expires December 10, 2021 [Page 7] openid-sse-framework June 2021 { "iss": "https://idp.example.com/", "jti": "756E69717565206964656E746966696572", "iat": 1520364019, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/risc/event-type/account-enabled": { "subject": { "format": "email", "email": "foo@example.com" } } } } Figure 5: Example: SET Containing a SSE Event with a Simple Subject Member { "iss": "https://idp.example.com/", "jti": "756E69717565206964656E746966696572", "iat": 1520364019, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/caep/event-type/session-revoked": { "subject": { "user": { "format": "iss_sub", "iss": "https://idp.example.com/3957ea72-1b66-44d6-a044-d805712b9288/", "sub": "jane.smith@example.com" }, "device": { "format": "iss_sub", "iss": "https://idp.example.com/3957ea72-1b66-44d6-a044-d805712b9288/", "sub": "e9297990-14d2-42ec-a4a9-4036db86509a" } } "initiating_entity": "policy", "reason_admin": "Policy Violation: C076E82F", "reason_user": "Landspeed violation.", "event_timestamp": 1600975810 } } } Figure 6: Example: SET Containing a SSE Event with a Complex Subject Member Tulshibagwale, et al. Expires December 10, 2021 [Page 8] openid-sse-framework June 2021 { "iss": "https://sp.example2.com/", "jti": "756E69717565206964656E746966696572", "iat": 1520364019, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": { "subject": { "format": "email", "email": "foo@example2.com" }, "event_timestamp": 1600975810, "claims": { "role": "ro-admin" } } } } Figure 7: Example: SET Containing a SSE Event with a Simple Subject and a Property Member { "iss": "https://myservice.example3.com/", "jti": "756E69717565206964656E746966696534", "iat": 15203800012, "aud": "636C69656E745F6324", "events": { "https://schemas.openid.net/secevent/caep/event-type/token-claims-change": { "subject": { "format": "catalog_item", "catalog_id": "c0384/winter/2354122" }, "event_timestamp": 1600975810, "claims": { "role": "ro-admin" } } } } Figure 8: Example: SET Containing a SSE Event with a Proprietary Subject Identifier Format Tulshibagwale, et al. Expires December 10, 2021 [Page 9] openid-sse-framework June 2021 6. Transmitter Configuration Discovery This section defines a mechanism for Receivers to obtain Transmitter configuration information. 6.1. Transmitter Configuration Metadata Transmitters have metadata describing their configuration: issuer REQUIRED. URL using the https scheme with no query or fragment component that the Transmitter asserts as its Issuer Identifier. This MUST be identical to the iss claim value in Security Event Tokens issued from this Transmitter. jwks_uri REQUIRED. URL of the Transmitter's JSON Web Key Set [RFC7517] document. This contains the signing key(s) the Receiver uses to validate signatures from the Transmitter. delivery_methods_supported RECOMMENDED. List of supported delivery method URIs. configuration_endpoint OPTIONAL. The URL of the Configuration Endpoint. status_endpoint OPTIONAL. The URL of the Status Endpoint. add_subject_endpoint OPTIONAL. The URL of the Add Subject Endpoint. remove_subject_endpoint OPTIONAL. The URL of the Remove Subject Endpoint. verification_endpoint OPTIONAL. The URL of the Verification Endpoint. critical_subject_members OPTIONAL. List of member names in a Complex Subject which, if present in a Subject Member in an event, MUST be interpreted by a Receiver. TODO: consider adding a IANA Registry for metadata, similar to Section 7.1.1 of [OAUTH-DISCOVERY]. This would allow other specs to add to the metadata. 6.2. Obtaining Transmitter Configuration Information Using the Issuer as documented by the Transmitter, the Transmitter Configuration Information can be retrieved. Tulshibagwale, et al. Expires December 10, 2021 [Page 10] openid-sse-framework June 2021 Transmitters supporting Discovery MUST make a JSON document available at the path formed by inserting the string "/.well-known/sse- configuration" into the Issuer between the host component and the path component, if any. The syntax and semantics of ".well-known" are defined in [RFC5785]. "sse-configuration" MUST point to a JSON document compliant with this specification and MUST be returned using the "application/json" content type. 6.2.1. Transmitter Configuration Request A Transmitter Configuration Document MUST be queried using an HTTP "GET" request at the previously specified path. The Receiver would make the following request to the Issuer "https://tr.example.com" to obtain its Configuration information, since the Issuer contains no path component: GET /.well-known/sse-configuration HTTP/1.1 Host: tr.example.com Figure 9: Example: Transmitter Configuration Request (without path) If the Issuer value contains a path component, any terminating "/" MUST be removed before inserting "/.well-known/sse-configuration" between the host component and the path component. The Receiver would make the following request to the Issuer "https://tr.example.com/issuer1" to obtain its Configuration information, since the Issuer contains a path component: GET /.well-known/sse-configuration/issuer1 HTTP/1.1 Host: tr.example.com Figure 10: Example: Transmitter Configuration Request (with path) Using path components enables supporting multiple issuers per host. This is required in some multi-tenant hosting configurations. This use of ".well-known" is for supporting multiple issuers per host; unlike its use in [RFC5785], it does not provide general information about the host. 6.2.2. Transmitter Configuration Response The response is a set of Claims about the Transmitter's configuration, including all necessary endpoints and public key location information. A successful response MUST use the 200 OK HTTP status code and return a JSON object using the "application/json" content type that contains a set of Claims as its members that are a Tulshibagwale, et al. Expires December 10, 2021 [Page 11] openid-sse-framework June 2021 subset of the Metadata values defined in Section 6.1. Other Claims MAY also be returned. Claims that return multiple values are represented as JSON arrays. Claims with zero elements MUST be omitted from the response. An error response uses the applicable HTTP status code value. HTTP/1.1 200 OK Content-Type: application/json { "issuer": "https://tr.example.com", "jwks_uri": "https://tr.example.com/jwks.json", "delivery_methods_supported": [ "https://schemas.openid.net/secevent/risc/delivery-method/push", "https://schemas.openid.net/secevent/risc/delivery-method/poll"], "configuration_endpoint": "https://tr.example.com/sse/mgmt/stream", "status_endpoint": "https://tr.example.com/sse/mgmt/status", "add_subject_endpoint": "https://tr.example.com/sse/mgmt/subject:add", "remove_subject_endpoint": "https://tr.example.com/sse/mgmt/subject:remove", "verification_endpoint": "https://tr.example.com/sse/mgmt/verification", "critical_subject_members": [ "tenant", "user" ] } Figure 11: Example: Transmitter Configuration Response 6.2.3. Transmitter Configuration Validation If any of the validation procedures defined in this specification fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used. The "issuer" value returned MUST be identical to the Issuer URL that was directly used to retrieve the configuration information. This MUST also be identical to the "iss" Claim value in Security Event Tokens issued from this Transmitter. Tulshibagwale, et al. Expires December 10, 2021 [Page 12] openid-sse-framework June 2021 7. Management API for SET Event Streams This section defines an HTTP API to be implemented by Event Transmitters and that can be used by Event Receivers to query and update the Event Stream configuration and status, to add and remove subjects and to trigger verification. This section is based on Management API for SET Event Streams [MGMTAPI]. +------------+ +------------+ | | Stream Config | | | Event <----------------+ Event | | Stream | | Receiver | | Management | Stream Status | | | API <----------------+ | | | | | | | Add Subject | | | <----------------+ | | | | | | | Remove Subject | | | <----------------+ | | | | | | | Stream Updated | | | +----------------> | | | | | | | Verification | | | <----------------+ | | | | | +------------+ +------------+ Figure 12: Event Stream Management API It is OPTIONAL for Transmitters to implement a Management API, but it is RECOMMENDED that they implement it, especially the endpoints for querying the Stream Status and for triggering Verification. 7.1. Event Stream Management Event Receivers manage how they receive events, and the subjects about which they want to receive events over an Event Stream by making HTTP requests to endpoints in the Event Stream Management API. A Transmitter and Receiver MAY use the same Event Stream for updates about multiple Subject Principals. The status of the Event Stream MAY be queried and managed independently for each Subject Principal by Transmitters and Receivers. Tulshibagwale, et al. Expires December 10, 2021 [Page 13] openid-sse-framework June 2021 The Event Stream Management API is implemented by the Event Transmitter and consists of the following endpoints: Configuration Endpoint An endpoint used to read the Event Stream's current configuration. Status Endpoint An endpoint used to read the Event Stream's current status. Add Subject Endpoint An endpoint used to add subjects to an Event Stream. Remove Subject Endpoint An endpoint used to remove subjects from an Event Stream. Verification Endpoint An endpoint used to request the Event Transmitter transmit a Verification Event over the Event Stream. An Event Transmitter MAY use the same URLs as endpoints for multiple streams, provided that the Event Transmitter has some mechanism through which they can identify the applicable Event Stream for any given request, e.g. from authentication credentials. The definition of such mechanisms is outside the scope of this specification. Within an Event Stream, events related to different Subject Principals MAY be managed independently. A Receiver MAY request Subject Principals to be added to or removed from a stream by Updating the Stream Status (Section 7.1.1.2) and specifying the Subject in the request. A Transmitter MAY decide to enable, pause or disable updates about a Subject independently of an update request from a Receiver. If a Transmitter decides to start or stop events for a Subject then the Transmitter MUST do the following according to the status of the stream If the stream is: Enabled the Transmitter MUST send a stream updated (Section 7.1.5) event respectively to the Receiver within the Event Stream. Paused the Transmitter SHOULD send stream updated (Section 7.1.5) after the Event Stream is re-started. A Receiver MUST assume that events may have been lost during the time when the event stream was paused. Tulshibagwale, et al. Expires December 10, 2021 [Page 14] openid-sse-framework June 2021 Disabled the Transmitter MAY send stream updated (Section 7.1.5) after the Event Stream is re-enabled. 7.1.1. Stream Status 7.1.1.1. Reading a Stream's Status An Event Receiver checks the current status of an event stream by making an HTTP GET request to the stream's Status Endpoint. The Stream Status method takes the following parameters: subject OPTIONAL. The subject for which the stream status is requested. On receiving a valid request the Event Transmitter responds with a 200 OK response containing a JSON [RFC7159] object with an attribute "status", whose string value MUST have one of the following values: enabled The Transmitter MUST transmit events over the stream, according to the stream's configured delivery method. paused The Transmitter MUST NOT transmit events over the stream. The transmitter will hold any events it would have transmitted while paused, and SHOULD transmit them when the stream's status becomes "enabled". If a Transmitter holds successive events that affect the same Subject Principal, then the Transmitter MUST make sure that those events are transmitted in the order of time that they were generated OR the Transmitter MUST send only the last events that do not require the previous events affecting the same Subject Principal to be processed by the Receiver, because the previous events are either cancelled by the later events or the previous events are outdated. disabled The Transmitter MUST NOT transmit events over the stream, and will not hold any events for later transmission. The following is a non-normative example request to check an event stream's status: GET /sse/status HTTP/1.1 Host: transmitter.example.com Authorization: Bearer zzzz Figure 13: Example: Check Stream Status Request Tulshibagwale, et al. Expires December 10, 2021 [Page 15] openid-sse-framework June 2021 The following is a non-normative example response: HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "status": "enabled" } Figure 14: Example: Check Stream Status Response The following is a non-normative example request to check an event stream's status for a specific subject: GET /sse/status?subject= HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= Figure 15: Example: Check Stream Status Request with Subject The following is a non-normative example response with a Subject claim: HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "status": "enabled", "subject": { "tenant" : { "format" : "iss_sub", "iss" : "http://example.com/idp1", "sub" : "1234" } } } Figure 16: Example: Check Stream Status Response Errors are signaled with HTTP status codes as follows: Tulshibagwale, et al. Expires December 10, 2021 [Page 16] openid-sse-framework June 2021 +------+------------------------------------------------------------+ | Code | Description | +------+------------------------------------------------------------+ | 401 | if authorization failed or it is missing | | | | | 403 | if the Event Receiver is not allowed to read the stream | | | status | | | | | 404 | if there is no Event Stream configured for this Event | | | Receiver, or if the Subject specified is invalid or if the | | | Receiver is not authorized to get status for the specified | | | Subject. | +------+------------------------------------------------------------+ Table 1: Read Stream Status Errors Examples: 1. If a Receiver makes a request with an invalid OAuth token, then the Transmitter MUST respond with a 401 error status. 2. If the Receiver presents a valid OAuth token, but the Transmitter policy does not permit the Receiver from obtaining the status, then the Transmitter MAY respond with a 403 error status. 3. If the Receiver requests the status for specific Subject, but the Transmitter policy does not permit the Receiver to read the status of that Subject, then the Transmitter MAY respond with a 404 error status in order to not reveal the policy decision. 4. If the specified Subject is invalid then the Transmitter MUST respond with a 404 error status. 7.1.1.2. Updating a Stream's Status An Event Receiver updates the current status of a stream by making an HTTP POST request to the Status Endpoint. The POST body contains a JSON [RFC7159] object with the following fields: status REQUIRED. The new status of the Event Stream. subject OPTIONAL. The Subject to which the new status applies. reason OPTIONAL. A short text description that explains the reason for the change. Tulshibagwale, et al. Expires December 10, 2021 [Page 17] openid-sse-framework June 2021 On receiving a valid request the Event Transmitter responds with a "200 OK" response containing a JSON [RFC7159] representation of the updated stream status in the body. The following is a non-normative example request to update an Event Stream's status: POST /sse/status HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= { "status": "paused" } Figure 17: Example: Update Stream Status Request Without Optional Fields The following is a non-normative example of an Update Stream Status request with optional fields: POST /sse/status HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= { "status": "paused", "subject": { "tenant" : { "format" : "iss_sub", "iss" : "http://example.com/idp1", "sub" : "1234" } }, "reason": "Disabled by administrator action." } Figure 18: Example: Update Stream Status Request With Optional Fields The following is a non-normative example response: Tulshibagwale, et al. Expires December 10, 2021 [Page 18] openid-sse-framework June 2021 HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "status": "paused" } Figure 19: Example: Update Stream Status Response Errors are signaled with HTTP status codes as follows: +------+------------------------------------------------------------+ | Code | Description | +------+------------------------------------------------------------+ | 202 | if the update request has been accepted, but not | | | processed. Receiver MAY try the same request later in | | | order to get processing result. | | | | | 400 | if the request body cannot be parsed or if the request is | | | otherwise invalid | | | | | 401 | if authorization failed or it is missing | | | | | 403 | if the Event Receiver is not allowed to update the stream | | | status | | | | | 404 | if there is no Event Stream configured for this Event | | | Receiver, or if an invalid Subject is specified. | +------+------------------------------------------------------------+ Table 2: Update Stream Status Errors Example: 1. If a Receiver makes a request to update the stream to enable it for a specific Subject, and the Transmitter is unable to decide whether or not to complete the request, then the Transmitter MUST respond with a 202 status code. 7.1.2. Stream Configuration An Event Stream's configuration is represented as a JSON [RFC7159] object with the following properties: iss Tulshibagwale, et al. Expires December 10, 2021 [Page 19] openid-sse-framework June 2021 *Read-Only*, A URL using the https scheme with no query or fragment component that the Transmitter asserts as its Issuer Identifier. This MUST be identical to the "iss" Claim value in Security Event Tokens issued from this Transmitter. aud *Read-Only*, A string or an array of strings containing an audience claim as defined in JSON Web Token (JWT) [RFC7519] that identifies the Event Receiver(s) for the Event Stream. This property cannot be updated. If multiple Receivers are specified then the Transmitter SHOULD know that these Receivers are the same entity. events_supported *Read-Only*, An array of URIs identifying the set of events supported by the Transmitter for this Receiver. If omitted, Event Transmitters SHOULD make this set available to the Event Receiver via some other means (e.g. publishing it in online documentation). events_requested *Read-Write*, An array of URIs identifying the set of events that the Receiver requested. A Receiver SHOULD request only the events that it understands and it can act on. This is configurable by the Receiver. events_delivered *Read-Only*, An array of URIs which is the intersection of "events_supported" and "events_requested". These events MAY be delivered over the Event Stream. delivery *Read-Write*, A JSON object containing a set of name/value pairs specifying configuration parameters for the SET delivery method. The actual delivery method is identified by the special key "method" with the value being a URI as defined in Section 11.2.1. min_verification_interval *Read-Only*, An integer indicating the minimum amount of time in seconds that must pass in between verification requests. If an Event Receiver submits verification requests more frequently than this, the Event Transmitter MAY respond with a 429 status code. An Event Transmitter SHOULD NOT respond with a 429 status code if an Event Receiver is not exceeding this frequency. format *Read-Write*, The Subject Identifier Format that the Receiver wants for the events. If not set then the Transmitter might Tulshibagwale, et al. Expires December 10, 2021 [Page 20] openid-sse-framework June 2021 decide to use a type that discloses more information than necessary. TODO: consider adding a IANA Registry for stream configuration metadata, similar to Section 7.1.1 of [OAUTH-DISCOVERY]. This would allow other specs to add to the stream configuration. 7.1.2.1. Reading a Stream's Configuration An Event Receiver gets the current configuration of a stream by making an HTTP GET request to the Configuration Endpoint. On receiving a valid request the Event Transmitter responds with a "200 OK" response containing a JSON [RFC7159] representation of the stream's configuration in the body. The following is a non-normative example request to read an Event Stream's configuration: GET /sse/stream HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= Figure 20: Example: Read Stream Configuration Request The following is a non-normative example response: Tulshibagwale, et al. Expires December 10, 2021 [Page 21] openid-sse-framework June 2021 HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "iss": "https://tr.example.com", "aud": [ "http://receiver.example.com/web", "http://receiver.example.com/mobile" ], "delivery": { "delivery_method": "https://schemas.openid.net/secevent/risc/delivery-method/push", "url": "https://receiver.example.com/events" }, "events_supported": [ "urn:example:secevent:events:type_1", "urn:example:secevent:events:type_2", "urn:example:secevent:events:type_3" ], "events_requested": [ "urn:example:secevent:events:type_2", "urn:example:secevent:events:type_3", "urn:example:secevent:events:type_4" ], "events_delivered": [ "urn:example:secevent:events:type_2", "urn:example:secevent:events:type_3" ] } Figure 21: Example: Read Stream Configuration Response Errors are signaled with HTTP status codes as follows: Tulshibagwale, et al. Expires December 10, 2021 [Page 22] openid-sse-framework June 2021 +------+------------------------------------------------------------+ | Code | Description | +------+------------------------------------------------------------+ | 401 | if authorization failed or it is missing | | | | | 403 | if the Event Receiver is not allowed to read the stream | | | configuration | | | | | 404 | if there is no Event Stream configured for this Event | | | Receiver | +------+------------------------------------------------------------+ Table 3: Read Stream Configuration Errors 7.1.2.2. Updating a Stream's Configuration An Event Receiver updates the current configuration of a stream by making an HTTP POST request to the Configuration Endpoint. The POST body contains a JSON [RFC7159] representation of the updated configuration. On receiving a valid request the Event Transmitter responds with a "200 OK" response containing a JSON [RFC7159] representation of the updated stream configuration in the body. The full set of editable properties must be present in the POST body, not only the ones that are specifically intended to be changed. Missing properties SHOULD be interpreted as requested to be deleted. Event Receivers should read the configuration first, modify the JSON [RFC7159] representation, then make an update request. Properties that cannot be updated MAY be present, but they MUST match the expected value. The following is a non-normative example request to update an Event Stream's configuration: Tulshibagwale, et al. Expires December 10, 2021 [Page 23] openid-sse-framework June 2021 POST /sse/stream HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= { "iss": "https://tr.example.com", "aud": [ "http://receiver.example.com/web", "http://receiver.example.com/mobile" ], "delivery": { "delivery_method": "https://schemas.openid.net/secevent/risc/delivery-method/push", "url": "https://receiver.example.com/events" }, "events_requested": [ "urn:example:secevent:events:type_2", "urn:example:secevent:events:type_3", "urn:example:secevent:events:type_4" ] } Figure 22: Example: Update Stream Configuration Request The following is a non-normative example response: Tulshibagwale, et al. Expires December 10, 2021 [Page 24] openid-sse-framework June 2021 HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "iss": "https://tr.example.com", "aud": [ "http://receiver.example.com/web", "http://receiver.example.com/mobile" ], "delivery": { "delivery_method": "https://schemas.openid.net/secevent/risc/delivery-method/push", "url": "https://receiver.example.com/events" }, "events_supported": [ "urn:example:secevent:events:type_1", "urn:example:secevent:events:type_2", "urn:example:secevent:events:type_3" ], "events_requested": [ "urn:example:secevent:events:type_2", "urn:example:secevent:events:type_3", "urn:example:secevent:events:type_4" ], "events_delivered": [ "urn:example:secevent:events:type_2", "urn:example:secevent:events:type_3" ] } Figure 23: Example: Update Stream Configuration Response Pending conditions or errors are signaled with HTTP status codes as follows: Tulshibagwale, et al. Expires December 10, 2021 [Page 25] openid-sse-framework June 2021 +------+------------------------------------------------------------+ | Code | Description | +------+------------------------------------------------------------+ | 202 | if the update request has been accepted, but not | | | processed. Receiver MAY try the same request later in | | | order to get processing result. | | | | | 400 | if the request body cannot be parsed or if the request is | | | otherwise invalid | | | | | 401 | if authorization failed or it is missing | | | | | 403 | if the Event Receiver is not allowed to update the stream | | | configuration | | | | | 404 | if there is no Event Stream configured for this Event | | | Receiver | +------+------------------------------------------------------------+ Table 4: Update Stream Configuration Errors 7.1.2.3. Removing a Stream Configuration An Event Receiver removes the configuration of a stream by making an HTTP DELETE request to the Configuration Endpoint. On receiving a request the Event Transmitter responds with a "200 OK" response if the configuration was successfully removed. The following is a non-normative example request to remove an Event Stream's configuration: DELETE /sse/stream HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= Figure 24: Example: Remove Stream Configuration Request Errors are signaled with HTTP status codes as follows: Tulshibagwale, et al. Expires December 10, 2021 [Page 26] openid-sse-framework June 2021 +------+------------------------------------------------------------+ | Code | Description | +------+------------------------------------------------------------+ | 401 | if authorization failed or it is missing | | | | | 403 | if the Event Receiver is not allowed to update the stream | | | configuration | +------+------------------------------------------------------------+ Table 5: Update Stream Configuration Errors 7.1.3. Subjects An Event Receiver can indicate to an Event Transmitter whether or not the receiver wants to receive events about a particular subject by "adding" or "removing" that subject to the Event Stream, respectively. 7.1.3.1. Adding a Subject to a Stream To add a subject to an Event Stream, the Event Receiver makes an HTTP POST request to the Add Subject Endpoint, containing in the body a JSON object the following claims: subject REQUIRED. A Subject claim identifying the subject to be added. verified OPTIONAL. A boolean value; when true, it indicates that the Event Receiver has verified the Subject claim. When false, it indicates that the Event Receiver has not verified the Subject claim. If omitted, Event Transmitters SHOULD assume that the subject has been verified. On a successful response, the Event Transmitter responds with an empty "200 OK" response. The Event Transmitter MAY choose to silently ignore the request, for example if the subject has previously indicated to the transmitter that they do not want events to be transmitted to the Event Receiver. In this case, the transmitter MAY return an empty "200 OK" response or an appropriate error code. See Security Considerations (Section 9). Errors are signaled with HTTP status codes as follows: Tulshibagwale, et al. Expires December 10, 2021 [Page 27] openid-sse-framework June 2021 +------+------------------------------------------------------------+ | Code | Description | +------+------------------------------------------------------------+ | 400 | if the request body cannot be parsed or if the request is | | | otherwise invalid | | | | | 401 | if authorization failed or it is missing | | | | | 403 | if the Event Receiver is not allowed to add this | | | particular subject, or not allowed to add in general | | | | | 404 | if the subject is not recognized by the Event Transmitter, | | | the Event Transmitter may chose to stay silent in this | | | case and respond with "200" | | | | | 429 | if the Event Receiver is sending too many requests in a | | | given amount of time | +------+------------------------------------------------------------+ Table 6: Add Subject Errors The following is a non-normative example request to add a subject to a stream, where the subject is identified by an Email Subject Identifier. POST /sse/subjects:add HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= { "subject": { "format": "email", "email": "example.user@example.com" }, "verified": true } Figure 25: Example: Add Subject Request The following is a non-normative example response to a successful request: HTTP/1.1 200 OK Server: transmitter.example.com Cache-Control: no-store Pragma: no-cache Figure 26: Example: Add Subject Response Tulshibagwale, et al. Expires December 10, 2021 [Page 28] openid-sse-framework June 2021 7.1.3.2. Removing a Subject To remove a subject from an Event Stream, the Event Receiver makes an HTTP POST request to the Remove Subject Endpoint, containing in the body a JSON object with the following claims: subject REQUIRED. A Subject claim identifying the subject to be removed. On a successful response, the Event Transmitter responds with a "204 No Content" response. Errors are signaled with HTTP status codes as follows: +------+------------------------------------------------------------+ | Code | Description | +------+------------------------------------------------------------+ | 400 | if the request body cannot be parsed or if the request is | | | otherwise invalid | | | | | 401 | if authorization failed or it is missing | | | | | 403 | if the Event Receiver is not allowed to remove this | | | particular subject, or not allowed to remove in general | | | | | 404 | if the subject is not recognized by the Event Transmitter, | | | the Event Transmitter may chose to stay silent in this | | | case and respond with "204" | | | | | 429 | if the Event Receiver is sending too many requests in a | | | given amount of time | +------+------------------------------------------------------------+ Table 7: Remove Subject Errors The following is a non-normative example request where the subject is identified by a Phone Number Subject Identifier: Tulshibagwale, et al. Expires December 10, 2021 [Page 29] openid-sse-framework June 2021 POST /sse/subjects:remove HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= { "subject": { "format": "phone", "phone_number": "+1 206 555 0123" } } Figure 27: Example: Remove Subject Request The following is a non-normative example response to a successful request: HTTP/1.1 204 No Content Server: transmitter.example.com Cache-Control: no-store Pragma: no-cache Figure 28: Example: Remove Subject Response 7.1.4. Verification In some cases, the frequency of event transmission on an Event Stream will be very low, making it difficult for an Event Receiver to tell the difference between expected behavior and event transmission failure due to a misconfigured stream. Event Receivers can request that a verification event be transmitted over the Event Stream, allowing the receiver to confirm that the stream is configured correctly upon successful receipt of the event. The acknowledgment of a Verification Event also confirms to the Event Transmitter that end-to-end delivery is working, including signature verification and encryption. An Event Transmitter MAY send a Verification Event at any time, even if one was not requested by the Event Receiver. 7.1.4.1. Verification Event The Verification Event is a standard SET with the following attributes: event type The Event Type URI is: "https://schemas.openid.net/secevent/sse/ event-type/verification". Tulshibagwale, et al. Expires December 10, 2021 [Page 30] openid-sse-framework June 2021 state OPTIONAL An opaque value provided by the Event Receiver when the event is triggered. This is a nested attribute in the event payload. Upon receiving a Verification Event, the Event Receiver SHALL parse the SET and validate its claims. In particular, the Event Receiver SHALL confirm that the value for "state" is as expected. If the value of "state" does not match, an error response of "setData" SHOULD be returned (see Section 2.3 of [DELIVERYPUSH] or [DELIVERYPOLL]). In many cases, Event Transmitters MAY disable or suspend an Event Stream that fails to successfully verify based on the acknowledgement or lack of acknowledgement by the Event Receiver. 7.1.4.2. Triggering a Verification Event. To request that a verification event be sent over an Event Stream, the Event Receiver makes an HTTP POST request to the Verification Endpoint, with a JSON [RFC7159] object containing the parameters of the verification request, if any. On a successful request, the event transmitter responds with an empty "204 No Content" response. Verification requests have the following properties: state OPTIONAL. An arbitrary string that the Event Transmitter MUST echo back to the Event Receiver in the verification event's payload. Event Receivers MAY use the value of this parameter to correlate a verification event with a verification request. If the verification event is initiated by the transmitter then this parameter MUST not be set. A successful response from a POST to the Verification Endpoint does not indicate that the verification event was transmitted successfully, only that the Event Transmitter has transmitted the event or will do so at some point in the future. Event Transmitters MAY transmit the event via an asynchronous process, and SHOULD publish an SLA for verification event transmission times. Event Receivers MUST NOT depend on the verification event being transmitted synchronously or in any particular order relative to the current queue of events. Errors are signaled with HTTP status codes as follows: Tulshibagwale, et al. Expires December 10, 2021 [Page 31] openid-sse-framework June 2021 +------+------------------------------------------------------------+ | Code | Description | +------+------------------------------------------------------------+ | 400 | if the request body cannot be parsed or if the request is | | | otherwise invalid | | | | | 401 | if authorization failed or it is missing | | | | | 429 | if the Event Receiver is sending too many requests in a | | | given amount of time; see related | | | "min_verification_interval" in Section 7.1.2 | +------+------------------------------------------------------------+ Table 8: Verification Errors The following is a non-normative example request to trigger a verification event: POST /sse/verify HTTP/1.1 Host: transmitter.example.com Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo= Content-Type: application/json; charset=UTF-8 { "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo=" } Figure 29: Example: Trigger Verification Request The following is a non-normative example response to a successful request: HTTP/1.1 204 No Content Server: transmitter.example.com Cache-Control: no-store Pragma: no-cache Figure 30: Example: Trigger Verification Response And the following is a non-normative example of a verification event sent to the Event Receiver as a result of the above request: Tulshibagwale, et al. Expires December 10, 2021 [Page 32] openid-sse-framework June 2021 { "jti": "123456", "iss": "https://transmitter.example.com", "aud": "receiver.example.com", "iat": 1493856000, "events": { "https://schemas.openid.net/secevent/sse/event-type/verification":{ "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo=" } } } Figure 31: Example: Verification SET 7.1.5. Stream Updated Event A Transmitter MAY change the stream status in reference to one or more Subjects without a request from a Receiver. The Transmitter sends an event of type "https://schemas.openid.net/secevent/sse/ event-type/stream-updated" to indicate that it has changed the status of the Event Stream for a specific Subject. If a Transmitter decides to change the status of an Event Stream from "enabled" to either "paused" or "disabled", then the Transmitter MUST send this event to any Receiver that is currently "enabled" to receive events for the specified Subject. If the Transmitter changes the status of the stream for a Subject from either "paused" or "disabled" to "enabled", then it MUST send this event to any Receiver that has previously been enabled to receive events for the specified Subject. The "stream-updated" event MAY contain the following claims: status REQUIRED. Defines the new status of the stream for the Subject Identifier specified in the Subject. reason OPTIONAL. Provides a short description of why the Transmitter has updated the status. subject OPTIONAL. Specifies the Subject Principal for whom the status has been updated. Tulshibagwale, et al. Expires December 10, 2021 [Page 33] openid-sse-framework June 2021 { "jti": "123456", "iss": "https://transmitter.example.com", "aud": "receiver.example.com", "iat": 1493856000, "events": { "https://schemas.openid.net/secevent/sse/event-type/stream-updated": { "subject": { "tenant" : { "format": "iss_sub", "iss" : "http://example.com/idp1", "sub" : "1234" } }, "status": "paused", "reason": "License is not valid" }, } } Figure 32: Example: Stream Updated SET 8. Authorization HTTP API calls from a Receiver to a Transmitter SHOULD be authorized by providing an OAuth 2.0 Access Token as defined by [RFC6750]. The receiver may obtain an access token using the Client Credential Grant [CLIENTCRED], or any other method suitable for the Receiver and the Transmitter. 9. Security Considerations 9.1. Subject Probing It may be possible for an Event Transmitter to leak information about subjects through their responses to add subject requests. A "404" response may indicate to the Event Receiver that the subject does not exist, which may inadvertently reveal information about the subject (e.g. that a particular individual does or does not use the Event Transmitter's service). Event Transmitters SHOULD carefully evaluate the conditions under which they will return error responses to add subject requests. Event Transmitters MAY return a "204" response even if they will not actually send any events related to the subject, and Event Receivers MUST NOT assume that a 204 response means that they will receive events related to the subject. Tulshibagwale, et al. Expires December 10, 2021 [Page 34] openid-sse-framework June 2021 9.2. Information Harvesting SETs may contain personally identifiable information (PII) or other non-public information about the event transmitter, the subject (of an event in the SET), or the relationship between the two. It is important for Event Transmitters to understand what information they are revealing to Event Receivers when transmitting events to them, lest the event stream become a vector for unauthorized access to private information. Event Transmitters SHOULD interpret add subject requests as statements of interest in a subject by an Event Receiver, and ARE NOT obligated to transmit events related to every subject an Event Receiver adds to the stream. Event Transmitters MAY choose to transmit some, all, or no events related to any given subject and SHOULD validate that they are permitted to share the information contained within an event with the Event Receiver before transmitting the event. The mechanisms by which such validation is performed are outside the scope of this specification. 9.3. Malicious Subject Removal A malicious party may find it advantageous to remove a particular subject from a stream, in order to reduce the Event Receiver's ability to detect malicious activity related to the subject, inconvenience the subject, or for other reasons. Consequently it may be in the best interests of the subject for the Event Transmitter to continue to send events related to the subject for some time after the subject has been removed from a stream. Event Transmitters MAY continue sending events related to a subject for some amount of time after that subject has been removed from the stream. Event Receivers MUST tolerate receiving events for subjects that have been removed from the stream, and MUST NOT report these events as errors to the Event Transmitter. 10. Privacy Considerations 10.1. Subject Information Leakage Event issuers and recipients SHOULD take precautions to ensure that they do not leak information about subjects via Subject Identifiers, and choose appropriate Subject Identifier Types accordingly. Parties SHOULD NOT identify a subject using a given Subject Identifier Type if doing so will allow the recipient to correlate different claims about the subject that they are not known to already have knowledge of. Transmitters and Receivers SHOULD always use the same Subject Identifier Type and the same claim values to identify a given subject Tulshibagwale, et al. Expires December 10, 2021 [Page 35] openid-sse-framework June 2021 when communicating with a given party in order to reduce the possibility of information leakage. 10.2. Previously Consented Data If SSE events contain new values for attributes of Subject Principals that were previously exchanged between the Transmitter and Receiver, then there are no additional privacy considerations introduced by providing the updated values in the SSE events, unless the attribute was exchanged under a one-time consent obtained from the user. 10.3. New Data Data that was not previously exchanged between the Transmitter and the Receiver, or data whose consent to exchange has expired has the following considerations: 10.3.1. Organizational Data If a user has previously agreed with a Transmitter that they agree to release certain data to third-parties, then the Transmitter MAY send such data in SSE events without additional consent of the user. Such data MAY include organizational data about the Subject Principal that was generated by the Transmitter. 10.3.2. Consentable Data If a Transmitter intends to include data in SSE events that is not previously consented to be released by the user, then the Transmitter MUST obtain consent to release such data from the user in accordance with the Transmitter's privacy policy. 11. Profiles This section is a profile of the following IETF SecEvent specifications: o "Security Event Token (SET)" [SET] o Push-Based SET Token Delivery Using HTTP [DELIVERYPUSH] o Poll-Based SET Token Delivery Using HTTP [DELIVERYPOLL] The RISC use cases that set the requirements are described in Security Events RISC Use Cases [USECASES]. The CAEP use cases that set the requirements are described in CAEP Use Cases (TODO: Add reference when file is added to repository.) Tulshibagwale, et al. Expires December 10, 2021 [Page 36] openid-sse-framework June 2021 11.1. Security Event Token Profile This section provides SSE profiling specifications for the "Security Event Token (SET)" [SET] spec. 11.1.1. Signature Key Resolution The signature key can be obtained through "jwks_uri", see Section 6. 11.1.2. SSE Event Subject The subject of a SSE event is identified by the "subject" claim within the event payload, whose value is a Subject Identifier. The "subject" claim is REQUIRED for all SSE events. The JWT "sub" claim MUST NOT be present in any SET containing a SSE event. 11.1.3. SSE Event Properties The SSE event MAY contain additional claims within the event payload that are specific to the event type. { "iss": "https://idp.example.com/", "jti": "756E69717565206964656E746966696572", "iat": 1520364019, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/risc/event-type/account-\ disabled": { "subject": { "format": "phone", "phone_number": "+1 206 555 0123" }, "reason": "hijacking", "cause-time": 1508012752 } } } Figure 33: Example: SET Containing a RISC Event with a Phone Number Subject Tulshibagwale, et al. Expires December 10, 2021 [Page 37] openid-sse-framework June 2021 { "iss": "https://idp.example.com/", "jti": "756E69717565206964656E746966696572", "iat": 1520364019, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/caep/event-type/token-claims-changed": { "subject": { "format": "email", "email": "user@example.com" }, "token": "some-token-value", } } } Figure 34: Example: SET Containing a CAEP Event with Properties 11.1.4. Explicit Typing of SETs SSE events MUST use explicit typing as defined in Section 2.3 of [SET]. { "typ":"secevent+jwt", "alg":"HS256" } Figure 35: Explicitly Typed JOSE Header The purpose is defense against confusion with other JWTs, as described in Sections 4.5, 4.6 and 4.7 of [SET]. While current Id Token [IDTOKEN] validators may not be using the "typ" header parameter, by requiring it for SSE SETs a distinct value is guaranteed for future validators. 11.1.5. The "exp" Claim The "exp" claim MUST NOT be used in SSE SETs. The purpose is defense in depth against confusion with other JWTs, as described in Sections 4.5 and 4.6 of [SET]. 11.1.6. The "aud" Claim The "aud" claim can be a single value or an array. Each value SHOULD be the OAuth 2.0 client ID. Other values that uniquely identifies Tulshibagwale, et al. Expires December 10, 2021 [Page 38] openid-sse-framework June 2021 the Receiver to the Transmitter MAY be used, if the two parties have agreement on the format. More than one value can be present if the corresponding Receivers are known to the Transmitter to be the same entity, for example a web client and a mobile client of the same application. All the Receivers in this case MUST use the exact same delivery method. If multiple Receivers have the exact same delivery configuration but the Transmitter does not know if they belong to the same entity then the Transmitter SHOULD issue distinct SETs for each Receiver and deliver them separately. In this case the multiple Receivers might use the same service to process SETs, and this service might reroute SETs to respective Receivers, an "aud" claim with multiple Receivers would lead to unintended data disclosure. { "jti": "123456", "iss": "https://transmitter.example.com", "aud": ["receiver.example.com/web", "receiver.example.com/mobile"], "iat": 1493856000, "events": { "https://schemas.openid.net/secevent/sse/event-type/verification": { "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo=" } } } Figure 36: Example: SET with array 'aud' claim 11.1.7. The "events" claim The "events" claim SHOULD contain only one event. Multiple event type URIs are permitted only if they are alternative URIs defining the exact same event type. 11.1.8. Security Considerations 11.1.8.1. Distinguishing SETs from other Kinds of JWTs Of particular concern is the possibility that SETs are confused for other kinds of JWTs. The Security Considerations section of [SET] has several sub-sections on this subject. The SSE Framework is asking for further restrictions: o The "sub" claim MUST NOT be present, as described in Section 11.1.2. Tulshibagwale, et al. Expires December 10, 2021 [Page 39] openid-sse-framework June 2021 o SSE SETs MUST use explicit typing, as described in Section 11.1.4. o The "exp" claim MUST NOT be present, as described in Section 11.1.5. 11.2. SET Token Delivery Using HTTP Profile This section provides SSE profiling specifications for the [DELIVERYPUSH] and [DELIVERYPOLL] specs. 11.2.1. Stream Configuration Metadata Each delivery method is identified by a URI, specified below by the "method" metadata. 11.2.1.1. Push Delivery using HTTP This section provides SSE profiling specifications for the [DELIVERYPUSH] spec. method "https://schemas.openid.net/secevent/risc/delivery-method/ push" endpoint_url The URL where events are pushed through HTTP POST. This is set by the Receiver. authorization_header The HTTP Authorization header that the Transmitter MUST set with each event delivery, if the configuration is present. The value is optional and it is set by the Receiver. 11.2.1.2. Polling Delivery using HTTP This section provides SSE profiling specifications for the [DELIVERYPOLL] spec. method "https://schemas.openid.net/secevent/risc/delivery-method/ poll" endpoint_url The URL where events can be retrieved from. This is specified by the Transmitter. 12. IANA Considerations Subject Identifiers defined in this document will be added to the "Security Events Subject Identifier Types" registry. This registry is defined in the Subject Identifiers for Security Event Tokens [SUBIDS] specification. Tulshibagwale, et al. Expires December 10, 2021 [Page 40] openid-sse-framework June 2021 13. References 13.1. Normative References [CLIENTCRED] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework - Client Credentials Grant", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [DELIVERYPOLL] Backman, A., Ed., Jones, M., Ed., Scurtescu, M., Ansari, M., and A. Nadalin, "Poll-Based SET Token Delivery Using HTTP", November 2020, . [DELIVERYPUSH] Backman, A., Ed., Jones, M., Ed., Hunt, P., Ed., Scurtescu, M., Ansari, M., and A. Nadalin, "Push-Based SET Token Delivery Using HTTP", November 2020, . [IDTOKEN] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 - ID Token", April 2017, . [OASIS.saml-core-2.0-os] Cantor, S., Kemp, J., Philpott, R., and E. Maler, "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", March 2005, . [OAUTH-DISCOVERY] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata - Version 10", June 2018, . [OPENID-DISCOVERY] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0", November 2014, . Tulshibagwale, et al. Expires December 10, 2021 [Page 41] openid-sse-framework June 2021 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, April 2010, . [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, . [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, . [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [SET] Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari, "Security Event Token (SET)", April 2018, . [SUBIDS] Backman, A., Ed. and M. Scurtescu, "Subject Identifiers for Security Event Tokens", May 2021, . 13.2. Non-Normative References [CAEP] Tulshibagwale, A., "Re-thinking Federated Identity with the Continuous Access Evaluation Protocol", February 2019, . Tulshibagwale, et al. Expires December 10, 2021 [Page 42] openid-sse-framework June 2021 [MGMTAPI] Scurtescu, M. and A. Backman, "Management API for SET Event Streams", June 2017, . [USECASES] Scurtescu, M., "Security Events RISC Use Cases", June 2017, . 13.3. URIs [1] https://datatracker.ietf.org/wg/secevent/about/ Appendix A. Acknowledgements The authors wish to thank all members of the OpenID Foundation Shared Signals and Events Working Group who contributed to the development of this specification. Transmitter Configuration Discovery (Section 6) is based on both OpenID Connect Discovery 1.0 [OPENID-DISCOVERY] and OAuth 2.0 Authorization Server Metadata [OAUTH-DISCOVERY]. Appendix B. Notices Copyright (c) 2021 The OpenID Foundation. The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF. The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make Tulshibagwale, et al. Expires December 10, 2021 [Page 43] openid-sse-framework June 2021 no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non- infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification. Authors' Addresses Atul Tulshibagwale Google Email: atultulshi@google.com Tim Cappalli Microsoft Email: tim.cappalli@microsoft.com Marius Scurtescu Coinbase Email: marius.scurtescu@coinbase.com Annabelle Backman Amazon Email: richanna@amazon.com John Bradley Yubico Email: secevemt@ve7jtb.com Tulshibagwale, et al. Expires December 10, 2021 [Page 44]