| Network Working Group | P. Hunt, Ed. |
| Internet-Draft | Oracle |
| Intended status: Standards Track | October 29, 2017 |
| Expires: May 2, 2018 |
SET Security Event Stream Management and Provisioning
draft-hunt-secevent-stream-mgmt-00
This specification defines a "control plane" service which enables a client (e.g. an Event Receiver) to establish, monitor, and manage a Security Event Token Stream.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 2, 2018.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This specification defines a "Control Plane" service that defines how an Event Receiver or its agent may provision, monitor, and manage the configuration of an Event Stream that delivers Security Event Tokens (see [I-D.ietf-secevent-token]) using delivery methods such as specified in the SET Delivery Using HTTP Specification (see [I-D.ietf-secevent-delivery]).
The specification defines the common metadata Event Transmitters and Receivers use to describe HTTP service endpoints, methods, optional signing and encryption modes, as well as the type and content of SETs delivered over a Stream. The specification defines how the Event Receiver parties may review and update the current configuration and confirm operational delivery status using HTTP over TLS.
The mandatory part of this specification (see Section 2) uses a profile of SCIM (see [RFC7643] and [RFC7644]) to implement Event Stream configuration, monitoring and retrieval using HTTP GET Section 4.3.1. Additionally, SCIM MAY be used to manage and update Event Stream configuration and operational state.
The choice os SCIM has been recommended as it is intended as a general purpose layer that can be applied to many underlying systems. SCIM's extensibility mechanisms to define data types (resource types) enable it to be flexibly used by specifications intenting to profile SET Tokens and Delivery for use in many ways.
For the purposes of the Control Plane, SCIM Section 2 provides the JSON data definitions that enable the Control Plane to allow service providers and clients to negotiate attributes and resource types used in different SET Profiles. This includes declarations and discovery of attribute types, mutability, cardinality, and returnability that MAY differ between deployments and SET Event type profiles. For HTTP protocol handling and error signaling, the processing rules in [RFC7644] SHALL be applied.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] . These keywords are capitalized when used to unambiguously specify requirements of the protocol or application features and behavior that affect the inter-operability and security of implementations. When these words are not capitalized, they are meant in their natural-language sense.
For purposes of readability examples are not URL encoded. Implementers MUST percent encode URLs as described in Section 2.1 of. Many examples show only partial response and may use ... to indicate omitted data.
Throughout this documents all figures MAY contain spaces and extra line-wrapping for readability and space limitations. Similarly, some URI's contained within examples, have been shortened for space and readability reasons.
This specification assumes terminology defined in the Security Event Token specification [I-D.ietf-secevent-token] and SET Token Delivery specification [I-D.ietf-secevent-delivery].
The following definitions are defined for Security Event distribution:
The Control Plane is an HTTP service associated with an Event Transmitter that enables the provisioning and monitoring of Event Streams by entities such Event Receivers, administrators, and monitoring services. This section describes required functionality to enable Event Receivers to retrieve configuration attributes and to detect SET delivery problems that may occur when an Event Transmitter fails to deliver SETs.
This specification also defines optional Control Plane services to create and update streams in sections Section 3 and Section 4.
An Event Stream is defined by a set of attributes which together define an Event Stream's operational configuration:
Additional Event Stream configuration (attributes) MAY be defined as extensions. The method for adding new attributes is defined in Section 3.3.
An Event Receiver MAY check the current status of a Stream the Event Transmitter's Control Plane service by performing an HTTP GET using the provided URI from the Event Transmitter either through an administrative process or via the optional Stream creation response defined in Section 3.1.
The format of the Stream GET request and response is defined by Section 3.4.
In addition to the basic attributes defined in Section 2 common to all resource types, an EventStream resource types uses the attributes defined in Section 2.1. As with any SCIM resource, an EventStream resource MUST include the JSON attributes schemas and id as defined in [RFC7643]:
The example below retrieves a specific EventStream resource whose id is 548b7c3f77c8bab33a4fef40.
GET /EventStreams/767aad7853d240debc8e3c962051c1c0 Host: example.com Accept: application/json Authorization: Bearer h480djs93hd8
Figure 1: Example EventStream HTTP GET Request
Below is an example response to the EventStream retrieval made in Figure 1.
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/EventStreams/767aad7853d240debc8e3c962051c1c0
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"fail",
"txErr":"connection",
"txErrDesc":"TCP connect error to notify.examplerp.com.",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}
Figure 2: Example Stream GET Response
In the above figure, the EventStream shows a status of fail due to a TCP connection error. In this case, the Event Receiver is able to discover that its endpoint was unavailable and has been marked failed by the Event Transmitter (possibly explaining a lack of received SETs). Typically, with this type of error, appropriate operations staff would be alerted and some corrective action would be taken to check for a configuration error or service failure.
The frequency with which Event Receivers poll the Event Stream status depends on factors such as:
In many cases Event Stream status monitoring may be triggered on a timeout basis. Event Receivers would typically poll if they have not received a SET for some period during which SETs would be expected based on past experience.
Receivers MAY use the endpoint /EventStreams to query and retrieve available Event Streams based on the provided Authorization header.
The example below retrieves any EventStream resources based solely on the requestor's authorization header.
GET /EventStreams/ Host: example.com Accept: application/json Authorization: Bearer h480djs93hd8
Figure 3: Example Stream HTTP GET Request From Common Endpoint
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/EventStreams/767aad7853d240debc8e3c962051c1c0
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":1,
"itemsPerPage":10,
"startIndex":1,
"Resources":[
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris_avail":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"fail",
"txErr":"connection",
"txErrDesc":"TCP connect error to notify.examplerp.com.",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}]
}
Figure 4: Example Event Stream List/Query Response Form
The Event Stream configuration attribute status reports the current state of an Event Stream with regards to whether the stream is operational or is in a suspended or failed state. Additionally, the status attribute can be used to pause or stop streams using the stream configuration update functions described in Section 3.
The following is the state machine representation of a Event Stream on a Event Transmitter. Note that a Event Stream cannot be made active until a verification process has been completed. As such, a newly created Event Stream begins with state on.
+
Create
|
+--------+ +------v-----+ +--------+
| +-Restart-> +--Suspend-> |
| fail | | on | | paused |
| <--Error--+ <--Resume--+ |
+--------+ +-+-------^--+ +---+----+
| | |
Disable Enable |
| | |
+-v-------+--+ |
| off <--Limited-----+
+------------+
Figure 5: Event Stream States at Event Transmitter
In Figure 5, the following actions impact the operational state of an Event Stream. status values are shown in the boxes, and change based on the following actions:
This section describes optional Stream management provisioning features that allow receivers or provisioning systems to create streams and update configuration to perform actions such as rotation, and operational state (e.g. suspend, stop, or resume) management.
The operations specified in this section are based on [RFC7644]. SCIM schema declarations for the EventStream resources are defined in Appendix A. HTTP Protocol usage and processing rules are provided by [RFC7644].
To define an Event Stream, the Event Receiver or its administrator (known as the client) first obtains an authorization credential allowing the ability to define a new Stream. Note: the process for registering to obtain credentials and permission to register is out-of-scope of this specification.
Upon obtaining authorization, the client issues an HTTP POST request as defined in Section 3.3. To complete the request, the administrative entity provides the required Stream configuration attributes as specified in Section 2.1, the delivery method [I-D.ietf-secevent-delivery] and any additional configuration specified by the SET Event Specifications that are being used.
The client MAY discover the Event Transmitter's Control Plane service for the schema requirements for EventStream resource type and any other extensions using SCIM schema discovery in Section 4.
The process to create an Event Stream is as follows:
In the following non-normative example, a request to create a new EventStream is submitted.
POST /EventStreams
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"description":"Logout events from oidc.example.com"
}
Figure 6: Example Create Event Stream Request
In following non-normative response, the Control Plane provider has automatically assigned an HTTP addressable location for the EventStream resource as well as an id. Additionally, the Control Plane response below includes additional configuration data for iss and iss_jwksUri.
HTTP/1.1 201 Created
Content-Type: application/scim+json
Location:
https://example.com/v2/EventStreams/767aad7853d240debc8e3c962051c1c0
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris_avail":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"on",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"iss":"oidc.example.com"
"iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks"
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}
Figure 7: Example Response to Create EventStream Request
Two HTTP methods are available to update an Event Stream configuration.
The HTTP PUT method allows a client having previously received the EventStream JSON document to modify the document and replace the Control Plane provider's copy. In using this method, the client is not required to remove data normally asserted or defined by the Event Stream Control Plane provider (e.g. attributes that are read only). The processing rules of [RFC7644] enable the client to "put back" what was previously received allowing the Control Plane provider to figure out what attributes need updating and which attributes are ignored. For example, while "id" is immutable, the Control Plane provider will simply ignore attempts to replace its value. When processing is complete the final accepted state is represented in the HTTP Response.
In the following non-normative example, a request to replace the existing EventStream EventStream is submitted. In this example, the change shown is the status is now set to off. Note that the client does not have to remove read-only attributes such as eventUris and eventUris_avail as these values are ignored as per Section 3.5.1.
PUT /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris_avail":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"off",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"iss":"oidc.example.com"
"iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks"
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}
Figure 8: Example Replace Event Stream Request
In following non-normative response, the Control Plane provider responds with the processed final state of the submitted EventStream.
HTTP/1.1 200 OK
Content-Type: application/scim+json
Location:
https://example.com/v2/EventStreams/767aad7853d240debc8e3c962051c1c0
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris_req":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"eventUris_avail":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"off",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"iss":"oidc.example.com"
"iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks"
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}
Figure 9: Example Response to PUT EventStream Request
Periodically, Event Receiver parties MAY have need to update an EventStream configuration for the purpose of:
As documented in Section 3.5.2, one or more PATCH operations (which are based on [RFC6902]) can be made against a single EventStream resource. The update is expressed as a JSON document. The JSON document contains an attribute Operations which contains an array of JSON objects each of which each have the following attributes:
In the following non-normative example, the client requests that the status configuration attribute be changed to paused for the EventStream whose path is identified by the request URI path.
PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"replace",
"path":"status",
"value":"paused"
}]
}
Figure 10: Example EventStream PATCH Request
In the above figure, upon receiving the request, the Event Transmitter would stop sending Events to the Receiver based on the requested value of status being set to paused.
In the following non-normative example, the client requests the addition and removal of two subjects from an existing EventStream. This operation is discussed further in Section 4.2.
PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"add",
"path":"subjects",
"value":{
"type":"EMAIL",
"value":"alice@example.com"
}
},
{
"op":remove",
"path":"subjects[value eq \"bob@example.com\"]
}]
}
Figure 11: Example Changing the Members of EventStream
The extensibility of SCIM enables many ways to model subjects that are part of an Event Stream. This section explores a few alternatives that profiling specifications could use to manage the contents of an Event Stream. These examples include managing subjects:
As a privacy and scalability consideration, profiling specifications SHOULD consider that most deployments SHOULD not allow the subjects that are part of an Event Stream to be enumerated in a single request. For example, in Section 4.2, the Event Stream configuration attribute subjects is typically not returned when querying Event Stream configurations (see Section 2.2). This is because the number of values may be too large (e.g. great than 100k values or even in the billions or more). Further, depending on the Security Event types being exchanged, Event Receivers MAY confirm that a subject is part of a stream for privacy reasons.
The ability to return attributes such as subjects is indicated by Control Plane service providers in schema discovery (see Section 4) as the schema attribute returned. For subjects this attribute SHOULD be set to request or never. In request mode, the client must specifically request the attribute subjects to have it enumerated. If the mode is never, the attribute SHALL NOT be returned to clients. In all cases however, a client MAY execute a query to verify the presence of a subject:
In this section, examples are given using the subjects attribute of Event Stream configuration described in Section 2.1
The following sections assume subject membership within streams is defined by the subjects attribute of the Event Stream configuration. As defined, subjects can support a number of value types including: OIDC Connect Subjects, SCIM Users and Groups, e-mail and telephone number identifiers, and URI referencable entities.
Checking subject membership is a matter of performing a query using a filter to achieve a match based on a value of the subjects attribute.
In this section, values have been added to the subjects attribute that are email addresses which clients to the Control Plane would like to verify are present or not. The subjects attribute has sub-attribute type set to EMAIL and the sub-attribute value contains an email address.
In the following non-normative example, a client queries the Control Plane to see if alice@example.com is part of any defined stream configuration. In the request, only the attribute id of the Event Stream is requested as the client does not need to see the rest of the Event Stream attributes. Note, for readability, the URL is not encoded.
GET /EventStreams?filter=(subjects.value eq "alice@example.com") &attributes=id Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8
Figure 12: Determining if an EMail Subject is in an Event Stream
In this non-normative example response, the subject is confirmed as not part of any Event Streams associated with the requester. In this case an empty list is returned with no values and totalResults is 0.
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":0,
"Resources":[]
}
Figure 13: Example Response With No Subject Match
In the response below, a match for subject alice@example.com is found and the id of the Event Stream configuration that contains the subject is returned is 767aad7853d240debc8e3c962051c1c0.
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":1,
"Resources":[
{
"id":"767aad7853d240debc8e3c962051c1c0",
...other meta attributes...
}
]
}
Figure 14: Example Response With Single Match
In this section, values in the subjects attribute are OIDC users which clients would like to verify are present. The attribute subjects has the sub-attribute type set to OIDC and the sub-attribute value contains an OIDC sub value and the iss sub-attribute contains the corresponding OIDC Provider iss value. For this example, the OIDC iss is op.example.com and the sub is 123456.
In the following non-normative example, a client queries the Control Plane to see if the above OIDC user is part of any defined stream configuration. In the request, only the attribute id is requested. Note, for readability, the URL is not encoded.
GET /EventStreams?filter=(subjects[value eq "123456" and iss eq "op.example.com"])&attributes=id Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8
Figure 15: Determining if an OIDC Subject is in an Event Stream
In the above request note that iss and value are enclosed within square brackets. This is done, per Figure 1 to ensure the matching condition within "[" and "]" is matched against the same JSON array record. If the filter was expressed as (subjects.value eq "123456" and subjects.iss eq "op.example.com") Then an improper match may occur because a composite value of subjects may have 123456 while another has op.example.com.
For examples of responses to Figure 15, see Figure 13 and Figure 14
Adding and removing subjects to an Event Stream is performed using the HTTP PATCH method described in Section 3.2.2. The following provides examples of adding and removing subjects based on EMAIL and OIDC subects.
In the following non-normative example, the client requests the addition of a subject identified by an EMAIL address to an existing EventStream. The composite value of subjects has the sub-attributes type and value which are assigned.
PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"add",
"path":"subjects",
"value":{
"type":"EMAIL",
"value":"alice@example.com"
}
}]
}
Figure 16: Adding an EMAIL Subject to a Stream
In the following non-normative example, the client requests the addition of an OIDC subject to an existing EventStream. The composite value of subjects has the sub-attributes type, iss, and value which are assigned.
PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"add",
"path":"subjects",
"value":{
"type":"OIDC",
"value":"123456",
"iss":"op.example.com"
}
}]
}
Figure 17: Adding an OIDC Provider Subject to a Stream
In the following non-normative example, the client requests the removal of a subject selected by using a filter against the subjects attribute.
PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"remove",
"path":"subjects[value eq \"123456\" and iss eq \"op.example.com\"]",
}]
}
Figure 18: Removing an OIDC Connect Subject from a Stream
SCIM defines a resource type called a Group which can be used as a container to manage one or more objects in a collection (See Section 4.2 of [RFC7643]). Groups work in similar fashion to the operations described in Section 4.2 except instead of operations against the 'subjects, the members attribute is used. Typically the value of the members attribute is the id of a local User or Group.
In order to use this method, the Stream configuration indicates the SCIM Group being used by adding Group as a member of the subjects attribute of the Stream configuration and indicating a type of Group.
The following is an example Stream configuration that has a Group as a member of the subjects. In the example below, e18c2dfb5d588 is the identifier of a SCIM Group containing a list of member resources.
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:EventStream"],
"id":"767aad7853d240debc8e3c962051c1c0",
"feedName":"OIDCLogoutFeed",
"eventUris":[
"http://schemas.openid.net/event/backchannel-logout"
],
"methodUri":"urn:ietf:params:set:method:HTTP:webCallback",
"deliveryUri":"https://notify.examplerp.com/Events",
"aud":"https://sets.myexamplerp.com",
"status":"off",
"maxDeliveryTime":3600,
"minDeliveryInterval":0,
"iss":"oidc.example.com"
"subjects":[
{
"type":"Group"
"value":"e18c2dfb5d588"
}
]
"iss_jwksUri":"https://example.com/keys/oidc-example-com.jwks"
"description":"Logout events from oidc.example.com",
"meta":{
... SCIM meta attributes ...
}
}
Figure 19: Event Stream Configured to Use SCIM Group
In this section, values have been added to the members attribute are id values of known SCIM resources. These values can be queried against the Group to see if the id is a member.
If the requester does not know the id of the resource for which they would like to check membership, a query can be performed as described in Section 3.4.
In the following non-normative example, a client queries the Control Plane to see if a User with id value of 413861904646 is a part of any Group. .
GET /Groups?filter=members.value eq "413861904646" &attributes=id Host: scim.example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8
Figure 20: Determining if a SCIM Resource is in a Event Stream Example
In this non-normative response, the id is confirmed as not part of the Group queried by the requester. In this case an empty list is returned with no values and totalResults is 0.
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":0,
"Resources":[]
}
Figure 21: Example Response With No Match
In the response below, a match for resource with an id value of 413861904646 is found and the id of any matched Groups that contain the id is returned. In this case a Group with an id value of e18c2dfb5d588 is returned.
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":1,
"Resources":[
{
"id":"e18c2dfb5d588",
}
]
}
Figure 22: Example Response With Single Match
Adding and removing Users to an Event Stream Group is performed using the HTTP PATCH method described in Section 3.2.2. The following provides examples of adding and removing Users to a Group
In the following non-normative example, the client requests the addition of a User identified by an id to an existing Group which is used by an Event Stream to denote member subjects.
PATCH /Groups/e18c2dfb5d588
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"add",
"path":"members",
"value":{
"type":"User",
"value":"8c16-01f8e146b87a"
}
}]
}
Figure 23: Example Adding a User to a Group
In the following non-normative example, the client requests the removal of a User identified by id with value 8c16-01f8e146b87a. The item to be removed is selected by using a filter against the members attribute.
PATCH /Groups/e18c2dfb5d588
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"remove",
"path":"members.value eq \"8c16-01f8e146b87a\"",
}]
}
Figure 24: Example Removing a User from a Group
This section demonstrates how to model subject participation in an Event Stream by treating subjects as a resource (a Subject). In this model, a subject is added, removed, and queried from an Event Stream by through HTTP POST, DELETE, and GET methods.
In this model, a new SCIM resource type is defined that describes the Subject resource and its associated schema.
The following is a non-normative example of a Resource Type definition that is configured in a SCIM service provider. The Resource Type defines the Subjects endpoint as well as a URI for the schema definition. The Resource Type configuration can be discovered by querying the SCIM service provider's /ResourceTypes endpoint (see Section 4).
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
"id": "Subject",
"name": "Subject",
"endpoint": "/Subjects",
"description": "Endpoint managing SECEVENT Subjects.",
"schema": "urn:ietf:params:scim:schemas:event:2.0:Subject",
"schemaExtensions": []
}
Figure 25: Example Resource Type Definition for Subjects
The following is an example schema definition for a Subject resource. This configuration can be retrieved from the SCIM Service Provider using the /Schemas endpoint (see Section 4).
{
"id" : "urn:ietf:params:scim:schemas:event:2.0:Subject",
"name" : "Subject",
"description" : "Subject stream configuration",
"attributes" : [
{
"name" : "email",
"type" : "string",
"multiValued" : false,
"description" : "The email of the subject being added to Event
Streams. The value SHOULD be specfied according to [RFC5321].",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "displayName",
"type" : "string",
"multiValued" : false,
"description" : "A simple representation of a Subject's name
that can be used for display purposes.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "streamId",
"type" : "string",
"multiValued" : fase,
"description" : "An Event Stream a Subject is part
of as identified by EventStream id",
"required" : false,
"mutability" : "readWrite",
"returned" : "default"
}
]
}
Figure 26: Example Schema for Subject Resources
To add a Subject to a Stream, an HTTP POST is used to create a new Subject resource which contains attributes identifying the subject and the associated Event Stream id.
The following non-normative example demonstrates adding a subject identified by example.user@example.com to an EventStream identified by id with value 767aad7853d240debc8e3c962051c1c0.
POST /Subjects/ HTTP/1.1
Host: transmitter.example.com
Authorization: Bearer eyJ0b2tlbiI6ImV4YW1wbGUifQo=
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:Subject"],
"email": "example.user@example.com",
"streamIds": "767aad7853d240debc8e3c962051c1c0",
"schemas":["urn:ietf:params:scim:schemas:event:2.0:Subject"]
}
Figure 27: Adding a Subject to a Stream Using POST
In response the server indicates the record is created and returns a permanent URI of the entry. This URI can later be used to remove the subject from the identified EventStream.
HTTP/1.1 201 Created
Content-Type: application/scim+json
Location:
https://example.com/v2/Subjects/e3c962051c1c0
{
"schemas":["urn:ietf:params:scim:schemas:event:2.0:Subject"],
"id": "e3c962051c1c0",
"email": "example.user@example.com",
"streamIds": "767aad7853d240debc8e3c962051c1c0",
"meta":{
...SCIM meta data...
}
}
Figure 28: Response to Adding a Subject to a Stream Using POST
Should the record be a duplicate Subject, the Control Plane implementation MAY choose to return the original resource registration and location with HTTP Status 200 (OK).
To query Subjects, SCIM filters can be used to return matching resources as per Section 3.4.2
Assuming the id of the EventStream is known, a query can be made against that identifier and the subjects identifier - in this case, an email address.
GET /Subjects?filter=(streamId eq "e3c962051c1c0" and email eq "example.user@example.com")
Figure 29: Querying if a Subject is in an EventStream
If a match to the request in Figure 29 is made, the following is a non-normative example response showing the matched Subject resource.
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults":1,
"Resources":[
{
"id":"e3c962051c1c0",
"email": "example.user@example.com"
"streamIds": "e3c962051c1c0",
"schemas":["urn:ietf:params:scim:schemas:event:2.0:Subject"],
...additional meta data...
}
]
}
Figure 30: Response to Query
To see if an email address is present in multiple EventStreams, the following query MAY be used.
GET /Subjects?filter=(email eq "example.user@example.com")
Figure 31: Querying All Event Streams for Subject
Assuming only one match is found, than a response similar to Figure 30 is returned. If not matches occur, a response is returned with totalResults equal to 0. If more than one match is returned, the additional matches are returned in the Resources array.
Assuming the id of the Subject resource is known, HTTP DELETE MAY be used. If it is not known, the id MAY be queried as per Section 4.4.2.
To remove a Subject resource perform an HTTP DELETE using the resource's URI (see Section 3.6).
DELETE /Subjects/e3c962051c1c0
Figure 32: Removing a Subject from an Event Stream
In the verify process, the Event Receiver organization initiates a request to the Event Transmitter to verify the Stream is working correctly. This can be used to both test for configuration errors (e.g. incorrect keys for signing and/or encryption, endpoints) and to verify operational state by using a Verify Event as an occasional 'ping' test.
To initiate a Verify Event, the Event Receiver organization using the Control Plane to set a nonce value for the Stream Configuration attribute verifyConfirm. Once set, the Event Transmitter SHALL issue a Verify SET the includes the client specified nonce value.
In the following non-normative example, the client requests a Verify Event by setting the attribute verifyNonce as part of the Event Stream configuration.
PATCH /EventStreams/767aad7853d240debc8e3c962051c1c0
Host: example.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op":"replace",
"path":"verifyNonce",
"value":"VGhpcyBpcyBhbi"
}]
}
Figure 33: Requesting a Verify using PATCH
Upon the changing of the Event Stream configuration attribute verifyNonce, the Event Transmitter sends a Verify Event SET to the Event Receiver using the registered methodUri mechanism.
The Verify SET contains the following attributes:
If the Event Stream is configured to encrypt SETs for the Event Receiver, then the SET MUST be encrypted with the provided key. Successful parsing of the message confirms that provides confirmation of correct configuration and possession of keys.
The following is a non-normative JSON representation of a Verify Event issued to an Event Receiver. Included in the SET is an example nonce value VGhpcyBpcyBhbi.
{
"jti": "123456",
"iss": "https://transmitter.example.com",
"aud": "receiver.example.com",
"iat": "1493856000",
"events": [
"urn:ietf:params:secevent:verification" : {
"nonce": "VGhpcyBpcyBhbi",
},
],
}
Figure 34: Example Verification SET
The above SET is encoded as a JWT and transmitted to the Event Receiver using the configured delivery method.
Upon receiving a verify SET, the Event Receiver SHALL parse the SET and verify its claims. In particular, the Event Receiver SHALL confirm that the values for nonce match the value assigned to verifyNonce in the Event Stream Configuration via the Control Plane. If the values do not match, administrative action should be taken to address the mis-configuration. Similarly if the SET is not received or is unparseable, the Event Receiver organization can check Event Stream configuration and check for errors by reviewing the Stream configuration attributes status and txErr.
See Section 7.5 for protocol specific privacy considerations.
The Privacy Considerations of SET Token Specification [I-D.ietf-secevent-token] and the SET Token Delivery specification [I-D.ietf-secevent-delivery] SHALL apply.
The exact set of subject entities upon which SETs can be issued SHOULD NOT be made available to any single party. This is because a subject's relationship with an Event Transmitter MAY change over time and may not be known to the Event Receiver. A design consideration is that an Event Receiver MUST already know personal identifiers before asking an Event Transmitter if there is an existing relationship by asking if that personal identifier is part of a stream. Accordingly the subjects attribute of an Event Stream can not normally be returned. Instead, a Control Plane provider MAY confirm a subject is part of a stream. See Section 4.1 and Section 4.2.1.
When receiving a request from a Control Plane client to add a subject, the provider SHOULD consider if the subject is appropriate to the purpose of the Event Stream being managed. For example, for an OpenID Connect Provider, was consent obtained to share security data with the Relying Party. Such authorization may have been previously authorized by a user via the OpenID consent process. Having obtained consent, the Control Plane provider SHOULD consider if the SET Events being requested to be streamed are appropriate.
This specification depends on the Security Considerations of [RFC7644].
Implementations SHOULD support access roles which enable different types of access to Event Streams via the Control Plane service. A minimal suggested set of roles includes: Section 7). The method by which these roles are implemented is out of scope of this specification.
Typically these roles are rights or scopes associated with the security credential presented in the HTTP Authorization header of requests (see
IANA is requested to add an entry to the 'IETF URN Sub-namespace for Registered Protocol Parameter Identifiers' registry and create a sub-namespace for the Registered Parameter Identifier as per [RFC3553]: urn:ietf:params:secevent:verification.
The identifier is used to indicate a Verify Event as defined in Section 5 for use in the events attribute defined in [I-D.ietf-secevent-token].
As per the "SCIM Schema URIs for Data Resources" registry established by Section 10.3, the following defines and registers the following SCIM URIs and Resource Types for Feeds and Event Streams.
| Schema URI | Name | ResourceType | Reference |
|---|---|---|---|
| urn:ietf:params:scim: schemas:event:2.0: EventStream | SET Event Stream | EventStream | Section 2.1 |
Attributes for SET Event Streams are defined in Section 2.1
SCIM Schema and ResourceType definitions are defined in Appendix A
| [I-D.ietf-secevent-delivery] | Hunt, P., Scurtescu, M., Ansari, M., Nadalin, A. and A. Backman, "SET Token Delivery Using HTTP", Internet-Draft draft-ietf-secevent-delivery-00, July 2017. |
| [I-D.ietf-secevent-token] | Hunt, P., Denniss, W., Ansari, M. and M. Jones, "Security Event Token (SET)", Internet-Draft draft-ietf-secevent-token-02, June 2017. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005. |
| [RFC5988] | Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010. |
| [RFC7231] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 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. |
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
"id": "EventStream",
"name": "EventStream",
"endpoint": "/EventStreams",
"description": "Endpoint and event configuration and status for SEC EVENT streams.",
"schema": "urn:ietf:params:scim:schemas:event:2.0:EventStream",
"schemaExtensions": []
}
Figure 35: SCIM EventStream Resource Type Definition
The EventStream resource type definition is defined as follows: /ResourceTypes endpoint of a SCIM service provider and informs SCIM clients about the endpoint location of EventStream resources and the SCIM schema used to define the resource. The corresponding schema for the EventStream resource MAY be retrieved from the SCIM /Schemas endpoint (see Section 3.2).
The attributes for the EventStream resource type are defined in Section 2.1.
{
"id" : "urn:ietf:params:scim:schemas:event:2.0:EventStream",
"name" : "EventStream",
"description" : "Event Stream Configuration",
"attributes" : [
{
"name" : "eventUris",
"type" : "string",
"multiValued" : true,
"description" : "An array of String value containing a logical
unique URI for Events that may be issued in the Stream",
"required" : false,
"caseExact" : false,
"mutability" : "readOnly",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "eventUris_req",
"type" : "string",
"multiValued" : true,
"description" : "An array of String value containing a logical
unique URI for Events that an Event Receiver is requesting.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "eventUris_avail",
"type" : "string",
"multiValued" : true,
"description" : "An array of String value containing a logical
unique URI for Events that are supported by the Transmitter",
"required" : false,
"caseExact" : false,
"mutability" : "readOnly",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "methodUri",
"type" : "string",
"multiValued" : false,
"description" : "A String value containing the URI for the
method used to deliver SET events. The method used indicates
the required configuration parameters for an
operational Event Stream configuration.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "deliveryUri",
"type" : "string",
"multiValued" : false,
"description" : "A String value containing the URI for a
feed endpoint used to pick up or deliver SET events based on
a configured method.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "iss",
"type" : "string",
"multiValued" : false,
"description" : "The URI for the publisher of the SETs that will
be issued for the Event Stream.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "aud",
"type" : "string",
"multiValued" : true,
"description" : "An OPTIONAL Array of JSON String values which
are URIs representing the audience(s) of the Event Stream.
Values SHALL be the value of SET "aud" claim sent to the Event
Receiver.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "iss_jwksUri",
"type" : "string",
"multiValued" : false,
"description" : "An OPTIONAL
String that contains the URL of the SET issuers public JSON
Web Key Set [RFC7517]. This contains the signing key(s) the
Event Receiver uses to validate SET signatures from the Event
Transmitter that will be used by the Event Receiver to verify
the authenticity of issued SETs.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "aud_jwksUri",
"type" : "string",
"multiValued" : false,
"description" : "An OPTIONAL JSON Web Key Set [RFC7517] that
contains the Event Receiver's encryption keys that MAY be used
by the Event Transmitter to encrypt SET tokens for the specified
Event Receiver.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "status",
"type" : "string",
"multiValued" : false,
"description" : "An OPTIONAL JSON String keyword that indicates
the current state of an Event Stream. More information on the E
vent Stream state can be found in Section 2.3.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none",
"canonicalValues" : [
"on",
"off",
"verify",
"paused",
"fail"
]
},
{
"name" : "maxRetries",
"type" : "integer",
"multiValued" : false,
"description" : "An OPTIONAL JSON number indicating the maximum
number of attempts to deliver a SET. A value of '0' indicates
there is no maximum. Upon reaching the maximum, the Event Stream
'status' attribute is set to 'failed'.",
"required" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "maxDeliveryTime",
"type" : "integer",
"multiValued" : false,
"description" : "An OPTIONAL number indicating the maximum
amount of time in seconds a SET MAY take for successful delivery
per request or cumulatively across multiple retries. Upon
reaching the maximum, the Event Stream 'status' is set to
'failed'. If undefined, there is no maximum time.",
"required" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "minDeliveryInterval",
"type" : "integer",
"multiValued" : false,
"description" : "An OPTIONAL JSON integer that represents the
minimum interval in seconds between deliveries. A value of '0'
indicates delivery should happen immediately. When delivery is
a polling method (e.g. HTTP GET), it is the expected time
between Event Receiver attempts. When in push mode (e.g.
HTTP POST), it is the interval the server will wait before
sending a new event or events.",
"required" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "txErr",
"type" : "string",
"multiValued" : false,
"description" : "An OPTIONAL JSON String keyword value. When
the Event Stream has 'status' set to 'fail', a keyword condition
is set.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none",
"canonicalValues" : [
"connection",
"tls",
"dnsname",
"receiver",
"other"
]
},
{
"name" : "txErrDesc",
"type" : "string",
"multiValued" : false,
"description" : "An OPTIONAL String value that is usually human
readable that provides further diagnostic detail by the
indicated 'txErr' error code.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "verifyNonce",
"type" : "string",
"multiValued" : false,
"description" : "An OPTIONAL String value that when changed
or set by a Control Plane client will cause the Event Transmitter
to issue a single Verify Event based on the value provided.",
"required" : false,
"caseExact" : false,
"mutability" : "writeOnly",
"returned" : "never",
"uniqueness" : "none"
},
{
"name" : "subjects",
"type" : "complex",
"multiValued" : true,
"description" : "An optional list of subjects that are part of
the Stream.",
"required" : false,
"subAttributes" : [
{
"name" : "value",
"type" : "string",
"multiValued" : false,
"description" : "Identifier of the member of this Group.
The contents of this parameter are determined by the value
of the sub-attribute 'type'.",
"required" : false,
"caseExact" : false,
"mutability" : "immutable",
"returned" : "default",
"uniqueness" : "none"
},
{
"name" : "type",
"type" : "string",
"multiValued" : false,
"description" : "A label indicating the type of resource,
e.g., OIDC Connect Subject, SAML Subject, Email address,
Telephone Number, SCIM User or SCIM Group, or the URI
of some other network addressable subject.",
"required" : false,
"caseExact" : false,
"canonicalValues" : [
"User",
"Group",
"OIDC",
"SAML"
"EMIL",
"PHONE",
"URI"
],
"mutability" : "immutable",
"returned" : "default",
"uniqueness" : "none"
}
],
"mutability" : "readWrite",
"returned" : "request"
}
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
}
},
The editors would like to thanks the members of the SCIM WG which began discussions of provisioning events starting with: draft-hunt-scim-notify-00 in 2015.
This draft is a re-work of material from Sections 2 and 4 of draft-hunt-secevent-distribution-01. The editor would like to thank Marius Scurtescu, Tony Nadalin, and Morteza Ansari for their contributions in previous drafts.
The editor would like to thank the participants in the the SECEVENTS working group for their support of this specification.
Draft 00 - PH - First Draft based on control plane portions of draft-hunt-idevent-distribution