Skip to main content

SCIM Profile for Security Event Tokens
draft-ietf-scim-events-03

Document Type Active Internet-Draft (scim WG)
Authors Phillip Hunt , Nancy Cam-Winget , Mike Kiser , Jen Schreiber
Last updated 2023-10-23
Replaces draft-hunt-scim-events
RFC stream Internet Engineering Task Force (IETF)
Intended RFC status (None)
Formats
Additional resources GitHub Repository
Mailing list discussion
Stream WG state WG Document
Document shepherd (None)
IESG IESG state I-D Exists
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ietf-scim-events-03
SCIM                                                        P. Hunt, Ed.
Internet-Draft                                             IndependentId
Intended status: Standards Track                           N. Cam-Winget
Expires: 25 April 2024                                     Cisco Systems
                                                                M. Kiser
                                                               Sailpoint
                                                            J. Schreiber
                                                                 Workday
                                                         23 October 2023

                 SCIM Profile for Security Event Tokens
                       draft-ietf-scim-events-03

Abstract

   This specification defines a set of SCIM Security Events using the
   Security Event Token Specification RFC8417 to enable the asynchronous
   exchange of messages between SCIM Service Providers and receivers.
   SCIM Security Events are typically used for: asynchronous request
   completion, resource replication, provisioning co-ordination, and
   shared security signals.

Status of This Memo

   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 25 April 2024.

Copyright Notice

   Copyright (c) 2023 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.

Hunt, et al.              Expires 25 April 2024                 [Page 1]
Internet-Draft           draft-ietf-scim-events             October 2023

   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 Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction and Overview . . . . . . . . . . . . . . . . . .   3
     1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   4
     1.2.  Notational Conventions  . . . . . . . . . . . . . . . . .   4
     1.3.  Definitions . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  SCIM Events . . . . . . . . . . . . . . . . . . . . . . . . .   6
     2.1.  Identifying the Subject of an Event . . . . . . . . . . .   6
     2.2.  Common Event Attributes . . . . . . . . . . . . . . . . .   8
     2.3.  SCIM Feed Events  . . . . . . . . . . . . . . . . . . . .   8
       2.3.1.  urn:ietf:params:SCIM:event:feed:add . . . . . . . . .   9
       2.3.2.  urn:ietf:params:SCIM:event:feed:remove  . . . . . . .   9
     2.4.  SCIM Provisioning Events  . . . . . . . . . . . . . . . .  10
       2.4.1.
               urn:ietf:params:SCIM:event:prov:create:{notice|full}   10
       2.4.2.
               urn:ietf:params:SCIM:event:prov:patch:{notice|full} .  12
       2.4.3.  urn:ietf:params:SCIM:event:prov:put:{notice|full} . .  14
       2.4.4.  urn:ietf:params:SCIM:event:prov:delete  . . . . . . .  16
       2.4.5.  urn:ietf:params:SCIM:event:prov:activate  . . . . . .  17
       2.4.6.  urn:ietf:params:SCIM:event:prov:deactivate  . . . . .  17
     2.5.  SCIM Signals Events . . . . . . . . . . . . . . . . . . .  17
       2.5.1.  urn:ietf:params:SCIM:event:sig:authMethod . . . . . .  18
       2.5.2.  urn:ietf:params:SCIM:event:sig:pwdReset . . . . . . .  18
     2.6.  Miscellaneous Events  . . . . . . . . . . . . . . . . . .  19
       2.6.1.  Asynchronous Events . . . . . . . . . . . . . . . . .  19
   3.  Event Delivery Feeds  . . . . . . . . . . . . . . . . . . . .  25
     3.1.  Security Event Token Signing and Encryption . . . . . . .  27
     3.2.  Point-to-Point Delivery Over HTTP . . . . . . . . . . . .  28
   4.  Events Discovery Schema for Service Provider Configuration  .  29
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  30
   6.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  31
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  31
     7.1.  SCIM Async Txn Header Registration  . . . . . . . . . . .  31
     7.2.  Registration of the SCIM Event URIs Sub-Registry  . . . .  32
     7.3.  Initial Events Registry . . . . . . . . . . . . . . . . .  33
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  34
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  34
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  35
   Appendix A.  Use Cases  . . . . . . . . . . . . . . . . . . . . .  36
     A.1.  Domain Based Replication  . . . . . . . . . . . . . . . .  37
     A.2.  Co-ordinated Provisioning . . . . . . . . . . . . . . . .  37

Hunt, et al.              Expires 25 April 2024                 [Page 2]
Internet-Draft           draft-ietf-scim-events             October 2023

     A.3.  Risk Signals  . . . . . . . . . . . . . . . . . . . . . .  40
   Appendix B.  Acknowledgments  . . . . . . . . . . . . . . . . . .  40
   Appendix C.  Change Log . . . . . . . . . . . . . . . . . . . . .  40
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  40

1.  Introduction and Overview

   This specification defines Security Events for SCIM Service Providers
   and receivers as specified by the Security Event Tokens (SET)
   [RFC8417] specification.  Scim Security Events in this specification
   include: asynchronous request completion, resource replication,
   provisioning co-ordination, and security signals.

   This specification also profiles the use of the HTTP Header "Prefer:
   Async-response" [RFC7240] to allow a SCIM Protocol Client [RFC7644]
   to request an asynchronous response (see Section 2.6.1.1).

   In a typical HTTP client-server relationship, a SCIM Protocol Client
   issues commands to a SCIM Service Provider using HTTP methods such as
   POST, PATCH, and DELETE [RFC7644] that cause a state change to a SCIM
   Resource.  When multiple independent SCIM Clients update SCIM
   resources, individual clients become out of date as state changes
   occur.  Some clients may need to be informed of these changes for co-
   ordination or reconciliation purposes.  This could be done using SCIM
   periodic SCIM GET requests over time, but this rapidly problematic as
   the number of changes and the number of resources increases.

   Security Event Tokens [RFC8417] and SCIM Events offers the ability to
   exchange messages that act as triggers for receivers to monitor over
   time in an asynchronous approach.  This enables greater scale and
   timeliness, where only changed information is exchanged between
   parties.

   A SET token conveys a signal about a state changes that has occurred
   in a publishing SCIM Service Provider.  That token may be of interest
   to one or more receivers and can be delivered asynchronously to the
   originating SCIM client making the change.  Unlike SCIM Protocol
   requests which convey protocol commands, Security Events describe
   statements of fact about changes that have already occurred at the
   SCIM Provider.  This approach allows the event receiver to determine
   the best local follow-up action to take within the context of the
   receiver.  For example, the receiver can reconcile intentional schema
   and population differences between the domain as the receiver.

Hunt, et al.              Expires 25 April 2024                 [Page 3]
Internet-Draft           draft-ietf-scim-events             October 2023

1.1.  Requirements Language

   The keywords "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.

1.2.  Notational Conventions

   For purposes of readability examples are not URL encoded.
   Implementers MUST percent encode URLs as described in Section 2.1 of
   [RFC3986].

   Throughout this document 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.

1.3.  Definitions

   This specification uses definitions from the following
   specifications:

   *  Json Web Tokens (JWT) [RFC7519],

   *  Security Event Tokens (SET) [RFC8417], and

   *  System for Cross-Domain Identity Management Protocol [RFC7644].

   In Json Web Tokens and Security Event Tokens the term "claim" is used
   to refer to JSON attribute values in a Json Web Token [RFC7519]
   structure.  The term "claim" in tokens is used to indicate that an
   attribute value may not be verified and its accuracy can be
   questioned.  In the context of SCIM, claims are referred to as
   attributes.  For the purposes of this specification claims and
   attributes are inter-changeable.  For consistency, JWT and SET IANA
   registered attributes will continue to be called claims, while event
   attributes (i.e. those in an event payload) will be referred to as
   attributes.

   Additionally, the following terms are defined:

Hunt, et al.              Expires 25 April 2024                 [Page 4]
Internet-Draft           draft-ietf-scim-events             October 2023

   Attributes and Claims
      The JWT specification [RFC7519] upon which SET is based uses the
      term "claims" to refer to attributes in a JSON token.  SCIM in
      contrast uses the term "attributes" to refer to JSON attributes.
      For the purposes of this draft, the terms "attributes" and
      "claims" are equivalent.

   CP
      Abbreviation for "Co-ordinated Provisioning" as defined in
      Appendix A.2.  In these relationships an Event Publisher and
      Receiver typically exchange resource change events without
      exchanging data.  For a receiver to know the value of the data,
      the Event Receiver usually has calls back to the SCIM Event
      Publisher domain to receive a new copy of data (e.g.  Uses a SCIM
      GET request).

   DBR
      Abbreviation for "Domain Based Replication" as defined in
      Appendix A.1.  In this mode because there is an administrative
      relationship spanning multiple operational domains, data shared in
      Events typically uses the full mode variation of change events
      including the data payload attribute.  This eliminates the need
      for a call back to retrieve additional data.

   Event Feed / Event Stream
      This describes the quality that a feed (aka stream) MAY be managed
      per receiving client.  A SET transfer (see [RFC8935] [RFC8936])
      service provider MAY offer to allow Event Receiver's to
      "subscribe" to specific event types or events about specific
      resources (see Feed Management events Section 2.3).

   Event Receiver
      An entity receives events typically via [RFC8935], [RFC8936], or
      HTTP GET (see Section 2.6.1.1).  In the case of SET Push Transfer
      [RFC8935], the Event Receiver is an HTTP Service Endpoint that
      receives requests.  In the case of SET Poll-Based Transfer
      [RFC8936], the receiver is an HTTP client that initiates HTTP
      request to an Event Publisher endpoint.

Hunt, et al.              Expires 25 April 2024                 [Page 5]
Internet-Draft           draft-ietf-scim-events             October 2023

   Event Publisher
      A system that issues SET tokens based on a resource state changes
      that have occurred at a SCIM Service Provider.  For example,
      events MAY be the result of a SCIM Create, Modify, or Delete as
      defined in [RFC7644].  A SCIM Service Provider MAY be an Event
      Publisher or an independent service that aggregates events into
      Event Receiver feeds.  As described above, when using [RFC8935],
      the Event Publisher is an HTTP Client that initiates HTTP POST
      requests to a defined Event Receiver endpoint.  When using
      [RFC8936], the Event Publisher provides an HTTP endpoint which a
      receiver MAY use to "poll" for Security Events.

   RS
      Abbreviation for "Risk Signals" as defined in Appendix A.3.

   SCIM Client
      An HTTP client that initiates SCIM Protocol [RFC7644] requests and
      receives responses.

   SCIM Service Provider
      An HTTP server that implements SCIM Protocol [RFC7644] and SCIM
      Schema [RFC7643].

   SET
      Abbreviation for "Security Event Token" as defined in [RFC8417]

2.  SCIM Events

   A SCIM event is a signal, in the form of a Security Event Token
   [RFC8417] that describe some event that has occurred.  A SET event
   consists of a set of standard JWT "top-level" claims, an "events"
   claim that contains one or more event URI subclaims (JSON attributes)
   each with a JSON object containing relevant event information.

2.1.  Identifying the Subject of an Event

   SCIM Events SHALL use the "sub_id" claim defined by Subject
   Identifiers for Security Event Tokens [SUBID] specification to
   identify the subject of events.  The sub_id claim MUST be contained
   within the main JWT claims body and SHALL NOT be located within an
   Event payload within the events claim.  A SET with multiple event
   URI's indicates that the events arise from the same transaction or
   resource state change for a single resource or subject.  Finally, as
   recommended in [RFC8417] the JWT "sub" claim SHALL NOT be used.

Hunt, et al.              Expires 25 April 2024                 [Page 6]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
        "iss": "issuer.example.com",
        "iat": 1508184845,
        "aud": "aud.example.com",
        "sub_id": {
           "format": "scim",
           "uri": "/Users/2b2f880af6674ac284bae9381673d462",
           "externalId": "alice@example.com"
        },
        "events": {
          ...
        }
   }

                     Figure 1: SCIM Subject Id Example

   The top-level claim "sub_id" SHALL contain the subclaim "format"
   whose value is set to scim to indicate the other attributes present
   are SCIM attributes.  The following sub_id attributes are defined:

   uri
      The SCIM relative path for the resource which usually consists of
      the resource type endpoint plus the resource id.  For example
      /Users/2b2f880af6674ac284bae9381673d462.  This attribute MUST be
      provided in a SCIM Event sub_id claim.  Note the relative path is
      the path component after the SCIM Service Provider Base URI as
      defined in Section 1.3 [RFC7644].  In cases where the Event
      Receiver is unable to match a URI, the Event Receiver MAY issue a
      call-back to a previously agreed SCIM Service Provider Base URI
      plus the relative uri value and perform a SCIM GET request per
      Section 3.4.1 [RFC7644].

   externalId
      If known, the externalId value of the SCIM Resource that MAY be
      used by a receiver to identify the corresponding resource in the
      Event Receiver's domain.

   id
      The SCIM Id attribute MAY be used for backwards compatibility
      reasons in addition to the uri claim.

   emails,username, ...
      A SCIM attribute that is unique to both the Event Publisher and
      Receiver.  Typically, attributes like email or usernames are used
      in situations where normal SCIM identifiers (id and externalId)
      are insufficient to identify a common resource between an Event
      Publisher and Event Receiver.

Hunt, et al.              Expires 25 April 2024                 [Page 7]
Internet-Draft           draft-ietf-scim-events             October 2023

2.2.  Common Event Attributes

   The following attributes are available for all events defined.  Some
   attributes are defined as SET/JWT claims, while others are "Event
   Payload" claims as defined in Section 1.2 [RFC8417].

   txn
      For the purposes of SCIM, this SET defined claim identifies a
      unique transaction originating at a SCIM Service Provider and/or
      its underlying data repository or database.  The claim is used to
      detect duplicate transactions that may have been received (e.g. in
      the case of a re-transmitted or recovered event).  If not
      provided, the SET jti claim MAY be used.  Where txn identifies a
      unique transaction within a SCIM Service Provider, multiple SETs
      MAY be issued each with distinct JTI's stemming from a common
      originating transaction with identical txn values.

   data
      This event payload attribute contains information described in
      SCIM Bulk Operations data attribute, Section 3.7 [RFC7644].  The
      JSON object contains the equivalent SCIM command processed by the
      SCIM Service provider.  For example, after processing a SCIM
      Create operation, the data contained includes the final
      representation of the created entity by the SCIM Service Provider
      including the assigned id value.

   attributes
      This payload attribute contains an array of attributes that were
      added, revised, or removed.  For example:
      "attributes": ["username","emails"]

   Only one of data or attributes claims SHALL be provided depending on
   the event definition.

   This specification defines a new URI prefix
   urn:ietf:params:SCIM:event which is used as the prefix for the
   following defined SCIM Events (see Section 7.2).

2.3.  SCIM Feed Events

   This section defines events related to changes in the content of an
   event feed.  For example, SCIM resources that are being added or
   removed from an event feed.  For example, the events may be used in
   Co-operative Provisioning scenarios where only a sub-set of entities
   are shared across an Event Feed.  The URI prefix for these events is:
   urn:ietf:params:SCIM:event:feed

Hunt, et al.              Expires 25 April 2024                 [Page 8]
Internet-Draft           draft-ietf-scim-events             October 2023

2.3.1.  urn:ietf:params:SCIM:event:feed:add

   The specified resource was added to the Event Feed.  A feed:add does
   not indicate a resource is new or has been recently created.  For
   example, an existing user has had a new role (e.g.  CRM_User) added
   to their profile which has caused their resource to join a feed.

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "txn": "b7b953f11cc6489bbfb87834747cc4c1",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/2b2f880af6674ac284bae9381673d462",
       "externalId": "jdoe"
     },
     "events":{
       "urn:ietf:params:SCIM:event:feed:add": {}
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                   Figure 2: Example SCIM Feed Add Event

2.3.2.  urn:ietf:params:SCIM:event:feed:remove

   The specified resource has been removed from the feed.  Removal does
   not indicate that the resource was deleted or otherwise deactivated.
   This event has minimal disclosure.

Hunt, et al.              Expires 25 April 2024                 [Page 9]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/2b2f880af6674ac284bae9381673d462"
       "externalId": "jdoe",
     },
     "events":{
       "urn:ietf:params:SCIM:event:feed:remove": {}
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                  Figure 3: Example SCIM Feed Remove Event

2.4.  SCIM Provisioning Events

   This section defines resource changes that have occurred within a
   SCIM Service Provider.  These events are used in both Domain Based
   Replication (DBR) and Co-operative Provisioning (CP) mode.  The URI
   prefix for these events is: urn:ietf:params:SCIM:event:prov

2.4.1.  urn:ietf:params:SCIM:event:prov:create:{notice|full}

   Indicates a new SCIM resource has been created by the SCIM Service
   Provider and has been added to the Event Feed.  When the data payload
   attribute is included, the event uri SHALL end with full otherwise,
   the event URI ends with notice.  In full mode, the set of values
   reflecting the final state of the resource at the service provider
   are provided using the data attribute.  In notice mode, attributes is
   returned disclosing the list of attributes included in the create
   request.  Note that because the event MAY be used for replication,
   the final id attribute that was assigned by the SCIM Service Provider
   is shared so that all replicas in the domain MAY use the same
   resource identifier.

Hunt, et al.              Expires 25 April 2024                [Page 10]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "4d3559ec67504aaba65d40b0363faad8",

     "iat": 1458496404,
     "iss":"https://scim.example.com",
     "aud":[
       "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754",
       "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7"
     ],
     "sub_id": {
       "format": "scim",
       "uri": "/Users/44f6142df96bd6ab61e7521d9",
        "externalId":"jdoe"
     }
     "events":{
       "urn:ietf:params:SCIM:event:prov:create:full":{
         "data":{
           "schemas":[ "urn:ietf:params:scim:schemas:core:2.0:User"],
           "emails":[
             {"type":"work","value":"jdoe@example.com"}
           ],
           "userName":"jdoe",
           "name":{
             "givenName":"John",
             "familyName":"Doe"
           }
         }
       }
     }
   }

                    Figure 4: Example SCIM Create (Full)

Hunt, et al.              Expires 25 April 2024                [Page 11]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "4d3559ec67504aaba65d40b0363faad8",
     "iat": 1458496404,
     "iss":"https://scim.example.com",
     "aud":[
       "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754",
       "https://scim.example.com/Feeds/5d7604516b1d08641d7676ee7"
     ],
     "sub_id": {
       "format": "scim",
       "uri": "/Users/44f6142df96bd6ab61e7521d9",
       "externalId": "jdoe"
     },
     "events": {
       "urn:ietf:params:SCIM:event:prov:create:notice": {
         "attributes": [
           "id",
           "name",
           "userName",
           "password",
           "emails"
         ]
       }
     }
   }

                Figure 5: Example SCIM Create Event (Notice)

   The event above notifies the Event Receiver which attributes have
   changed but does not convey the actual information.  The Event
   Receiver MAY retrieve that information by performing a SCIM GET to
   the sub value specified.

2.4.2.  urn:ietf:params:SCIM:event:prov:patch:{notice|full}

   The specified resource has been updated using SCIM PATCH.  In full
   mode, the data payload attribute is included.  When the event URI
   ends with notice, the list of attributes changed is provided.

Hunt, et al.              Expires 25 April 2024                [Page 12]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "sub_id": {
       "format": "scim",
       "uri": "/Groups/176f397ec4c44b94b2cfcb759780b8c2",
       "externalId": "crmUsers"
     },
     "events":{
       "urn:ietf:params:SCIM:event:prov:patch:full": {
         "version": "a330bc54f0671c9",
         "data": {
           "schemas":
         ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
           "Operations":[{
             "op":"add",
             "path":"members",
             "value":[{
                "display": "Babs Jensen",
                "$ref": "/Users/2819c223...413861904646",
                "value": "2819c223-7f76-453a-919d-413861904646"
             }]
           }]
         }
       }
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                 Figure 6: Example SCIM Patch Event (Full)

Hunt, et al.              Expires 25 April 2024                [Page 13]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "sub_id": {
       "format": "scim",
       "uri": "/Groups/176f397ec4c44b94b2cfcb759780b8c2",
       "externalId": "crmUsers"
     },
     "events":{
       "urn:ietf:params:SCIM:event:prov:patc:notice": {
         "attributes": ["members"],
         "version": "a330bc54f0671c9"
       }
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                Figure 7: Example SCIM Patch Event (Notice)

2.4.3.  urn:ietf:params:SCIM:event:prov:put:{notice|full}

   The specified resource has been updated (e.g. one or more attributes
   has changed).  In full mode, the SCIM PUT request body is included in
   the data attribute.  In notice mode the modified attributes are
   listed using attributes.

Hunt, et al.              Expires 25 April 2024                [Page 14]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/2819c223-7f76-453a-919d-413861904646"
     },
     "events":{
       "urn:ietf:params:SCIM:event:prov:put:full": {
         "version": "a330bc54f0671c9",
         "data": {
           "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
           "userName":"jdoe",
           "externalId":"jdoe",
           "name":{
              "formatted":"Mr. Jon Jack Doe III",
              "familyName":"Doe",
              "givenName":"Jon",
              "middleName":"Jack"
           },
           "roles":[],
           "emails":[
             {"value":"jdoe@example.com"},
             {"value":"anon@jdoe.org"}
           ]
         }
       }
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                  Figure 8: Example SCIM Put Event (Full)

Hunt, et al.              Expires 25 April 2024                [Page 15]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/2819c223-7f76-453a-919d-413861904646"
     },
     "events":{
       "urn:ietf:params:SCIM:event:prov:put:notice": {
         "version": "a330bc54f0671c9",
         "attributes": ["userName","externalId","name","roles","emails"]
       }
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                 Figure 9: Example SCIM Put Event (Notice)

2.4.4.  urn:ietf:params:SCIM:event:prov:delete

   The specified resource has been deleted from the SCIM Service
   Provider.  The resource is also removed from the feed.  When a DELETE
   is sent, a corresponding feedRemove is not issued.  A delete event
   has no payload attributes.  Note that because the delete event has no
   attributes, the qualifiers full and notice SHALL NOT be used.

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/2b2f880af6674ac284bae9381673d462",
       "externalId": "jDoe"
     },
     "events":{
       "urn:ietf:params:SCIM:event:prov:delete": {}
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                    Figure 10: Example SCIM Delete Event

Hunt, et al.              Expires 25 April 2024                [Page 16]
Internet-Draft           draft-ietf-scim-events             October 2023

2.4.5.  urn:ietf:params:SCIM:event:prov:activate

   The specified resource (e.g.  User) has been "activated".  This does
   not necessarily reflect any particular state change at the SCIM
   Service Provider but may simply indicate the account defined by the
   SCIM resource is ready for use as agreed upon by the Event Publisher
   and Event Receiver.  For example, an activated resource represents an
   account that may be logged in.

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/2b2f880af6674ac284bae9381673d462"
     },
     "events":{
       "urn:ietf:params:SCIM:event:prov:activate": {}
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                   Figure 11: Example SCIM Activate Event

2.4.6.  urn:ietf:params:SCIM:event:prov:deactivate

   The specified resource (e.g.  User) has been deactivated and
   disabled.  The exact meaning SHOULD be agreed to by the Event
   Publisher and its corresponding Event Receiver.  Typically, this
   means the sub may no longer have an active security session.  As with
   the activate event, this event has minimal disclosure requirements.

2.5.  SCIM Signals Events

   This section defines security signal events that have occurred within
   a SCIM Service Provider.  The URI prefix for these events is:
   urn:ietf:params:SCIM:event:signal

Hunt, et al.              Expires 25 April 2024                [Page 17]
Internet-Draft           draft-ietf-scim-events             October 2023

2.5.1.  urn:ietf:params:SCIM:event:sig:authMethod

   A new authentication method has been added to the User profile.  As
   attackers often use new authentication methods to lock-out Users from
   their account, this signal can be used by the receiver that the
   chance of account them may be temporarily elevated.  The receiver MAY
   also wish to take action such as resetting current authorizations or
   sessions.

   {
     "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/44f6142df96bd6ab61e7521d9"
     },
     "events":{
       "urn:ietf:params:SCIM:event:sig:authMethod": {}
     },
     "iat": 1458496025,
     "iss": "https://scim.example.com"
   }

         Figure 12: Example SCIM Authentication Factor Change Event

2.5.2.  urn:ietf:params:SCIM:event:sig:pwdReset

   The specified resource (e.g.  User) has changed its password or the
   password has been reset.  When the password has changed, the
   attributes attribute is supplied with the value "password".

   {
     "jti": "3d0c3cf797584bd193bd0fb1bd4e7d30",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/44f6142df96bd6ab61e7521d9"
     },
     "events": {
       "urn:ietf:params:SCIM:event:sig:pwdReset": {}
     },
     "iat": 1458496025,
     "iss": "https://scim.example.com",
     "aud":[
       "https://jhub.example.com/Feeds/98d52461fa5bbc879593b7754",
       "https://jhub.example.com/Feeds/5d7604516b1d08641d7676ee7"
     ]
   }

               Figure 13: Example SCIM Password Change Event

Hunt, et al.              Expires 25 April 2024                [Page 18]
Internet-Draft           draft-ietf-scim-events             October 2023

2.6.  Miscellaneous Events

   This section defines events related miscellaneous events such as
   Asynchronous Request completion that has occurred within a SCIM
   Service Provider.  The URI prefix for these events is:
   urn:ietf:params:SCIM:event:misc

2.6.1.  Asynchronous Events

2.6.1.1.  Making an Asynchronous SCIM Request

   A SCIM client making SCIM HTTP requests defined in [RFC7644] MAY
   request "asynchronous" processing using the "Prefer" HTTP Header as
   defined in Section 4.1 [RFC7240].  The client may do this for a
   number of reasons such as: avoiding holding HTTP connections open
   during long requests, because the result of the request is not
   needed, or for co-ordination reasons where the result is delivered to
   another entity for further action.

   To initiate an async SCIM request, a normal SCIM protocol POST, PUT,
   PATCH, or DELETE request is performed with the HTTP Header Prefer
   with a value of respond-async as defined in [RFC9110].  The HTTP
   Accept header SHALL be ignored.

   In response, and as indicated in the SCIM Service Provider
   Configuration (see Section 4, The SCIM Service Provider responds with
   either a normal SCIM response, or respond asynchronously by returning
   HTTP Status 202 Accepted.  The asynchronous response SHOULD contain
   no response body.  To enable correlation of the future event, the
   HTTP response header "Set-txn" is returned with a value corresponding
   to a future Security Event Token to be received whose "txn" claim
   SHALL match.  Per Section 3 [RFC7240], the response will also include
   the header Preference-Applied.  The Location header returned SHALL be
   one of the following:

   *  A location URI where the completion token MAY be retrieved using
      HTTP GET, or

   *  The normal SCIM location header response specified by [RFC7644].

   In the following non-normative example, a "Prefer" header is set to
   "respond-async":

Hunt, et al.              Expires 25 April 2024                [Page 19]
Internet-Draft           draft-ietf-scim-events             October 2023

   PUT /Users/2819c223-7f76-453a-919d-413861904646
   Host: scim.example.com
   Prefer: respond-async
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8
   {
     "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id":"2819c223-7f76-453a-919d-413861904646",
     "userName":"bjensen",
     "externalId":"bjensen",
     "name":{
       "formatted":"Ms. Barbara J Jensen III"
     },
     "roles":[],
     "emails":[
       {
           "value":"bjensen@example.com"
       }
     ]
   }

           Figure 14: Example Asynchronous SCIM Protocol Request

   The SCIM Service Provider responds with HTTP 202 Accepted and
   includes the Set-txn header:

   HTTP/1.1 202 Accepted
   Set-txn: 734f0614e3274f288f93ac74119dcf78
   Preference-Applied: respond-async
   Location:
     "/Users/2819c223-7f76-453a-919d-413861904646"

                                 Figure 15

2.6.1.2.  Asynchronous Bulk Endpoint Requests

   SCIM Protocol Section 3.7 [RFC7644] provides the ability to submit
   multiple SCIM operations in a single request.  When an asynchronous
   response is requested, a single Async Request Completion Event SHALL
   be generated for each requested operation.  For example, if a single
   SCIM Bulk request had 10 operations, then 10 Async Event completions
   events would be generated.

   The "txn" claim MUST be set to the value originally returned to the
   requesting SCIM client (see Section 2.6.1.1) appended with a dash "-"
   followed by the request operation number.  For example, if the "txn"
   claim value was "2d80e537a3f64622b0347b641ebc8f44", then the first
   Async Response Event Token representing the first operation SHALL

Hunt, et al.              Expires 25 April 2024                [Page 20]
Internet-Draft           draft-ietf-scim-events             October 2023

   have a "txn" claim value of "2d80e537a3f64622b0347b641ebc8f44-1", the
   second operation SHALL have a value of
   "2d80e537a3f64622b0347b641ebc8f44-2", and so on.

   If a SCIM service provider elects to optimize the sequence of
   operations (per Section 3.7 [RFC7644]), the Async Request Completion
   events generated MAY also be generated out of sequence from the order
   of operations in the original request.  In this case, the "txn"
   claims generated SHALL use operation numbers that correspond to the
   original request order.

2.6.1.3.  urn:ietf:params:SCIM:event:misc:asyncResp

   The Async Response event signals the completion of a SCIM request.
   The event payload contains the attributes defined in SCIM Bulk
   Section 3.7 [RFC7644] and is the same a single SCIM Bulk Response
   Operation as per Section 3.7.3.  In the event, the "txn" claim must
   be set to the value originally returned to the requesting SCIM client
   (see Section 2.6.1.1).

   {
     "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/2819c223-7f76-453a-919d-413861904646"
     },
     "txn": "734f0614e3274f288f93ac74119dcf78",
     "events":{
       "urn:ietf:params:SCIM:event:misc:asyncResp": {
           "method": "PUT",
           "version": "W\/\"huJj29dMNgu3WXPD\"",
           "status": "200"
       }
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

                Figure 16: Example SCIM Async Response Event

Hunt, et al.              Expires 25 April 2024                [Page 21]
Internet-Draft           draft-ietf-scim-events             October 2023

   An error may occur in the SCIM server's asynchronous processing of
   the SCIM request.  In that case, the event's operation MUST include a
   "response" attribute to indicate a non-200-series HTTP status as
   defined in Section 3.7 [RFC7644].  The response attribute MUST
   contain the sub-attributes defined in Section 3.12 [RFC7644].  Note
   that the "status" attribute of the event operation should match the
   "status" attribute of the response.

  {
   "jti": "6164f3bbf6ff41a88dc94f18cb0620e8",
   "sub_id": {
     "format": "scim",
     "uri": "/Users/2819c223-7f76-453a-919d-413861904646"
   },
   "txn": "734f0614e3274f288f93ac74119dcf78",
   "events":{
     "urn:ietf:params:SCIM:event:misc:asyncResp": {
         "method": "PUT",
         "version": "W\/\"huJj29dMNgu3WXPD\"",
         "status": "400",
         "response": {
             "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
             "scimType":"invalidSyntax",
             "detail": "Request is unparsable",
             "status":"400"
         }
     }
   },
   "iat": 1458505044,
   "iss":"https://scim.example.com",
   "aud":[
    "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
   ]
  }

            Figure 17: Example SCIM Async Error Response Event

   The following 4 figures show Async Completion events for the example
   in Section 3.7.3 of [RFC7644].

Hunt, et al.              Expires 25 April 2024                [Page 22]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "dbae9d7506b34329aa7f2f0d3827848b",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a"
     },
     "txn": "2d80e537a3f64622b0347b641ebc8f44-1",
     "events":{
       "urn:ietf:params:SCIM:event:misc:asyncResp": {
            "method": "POST",
            "bulkId": "qwerty",
            "version": "W\/\"oY4m4wn58tkVjJxK\"",
            "status": "201"
       }
     },
     "iat": 1458505044,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

         Figure 18: Example SCIM Async Response Event Operation 1/4

   {
     "jti": "ca977d05ba5c43929e3a69023d5392a9",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/b7c14771-226c-4d05-8860-134711653041"
     },
     "txn": "2d80e537a3f64622b0347b641ebc8f44-2",
     "events":{
       "urn:ietf:params:SCIM:event:misc:asyncResp": {
             "method": "PUT",
             "version": "W\/\"huJj29dMNgu3WXPD\"",
             "status": "200"
       }
     },
     "iat": 1458505045,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

         Figure 19: Example SCIM Async Response Event Operation 2/4

Hunt, et al.              Expires 25 April 2024                [Page 23]
Internet-Draft           draft-ietf-scim-events             October 2023

   {
     "jti": "4bb87d70a4ab463bbdcd1f99111cbbf1",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc"
     },
     "txn": "2d80e537a3f64622b0347b641ebc8f44-3",
     "events":{
       "urn:ietf:params:SCIM:event:misc:asyncResp": {
             "method": "PATCH",
             "version": "W\/\"huJj29dMNgu3WXPD\"",
             "status": "200"
       }
     },
     "iat": 1458505046,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

         Figure 20: Example SCIM Async Response Event Operation 3/4

   {
     "jti": "6a7843a7f5244d0eb62ca38b641d9139",
     "sub_id": {
       "format": "scim",
       "uri": "/Users/e9025315-6bea-44e1-899c-1e07454e468b"
     },
     "txn": "2d80e537a3f64622b0347b641ebc8f44-4",
     "events":{
       "urn:ietf:params:SCIM:event:misc:asyncResp": {
             "method": "DELETE",
             "status": "204"
       }
     },
     "iat": 1458505047,
     "iss":"https://scim.example.com",
     "aud":[
      "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
     ]
   }

         Figure 21: Example SCIM Async Response Event Operation 4/4

Hunt, et al.              Expires 25 April 2024                [Page 24]
Internet-Draft           draft-ietf-scim-events             October 2023

3.  Event Delivery Feeds

   In addition to retrieving a single security event as described in
   Section 2.6.1.1, Event Feeds (or Streams) provide the ability
   exchange a series of events between pre-arranged endpoints using the
   following Security Event Token exchange methods:

   [RFC8935]
      Push-Based Security Event Token (SET) Delivery delivers tokens to
      an Event Receiver with an accessible HTTP Endpoint.

   [RFC8936]
      Poll-Based Security Event Token (SET) Delivery enables an event
      receiver to initiate calls to SET Event publisher endpoint to
      receive 1 or more events.  This is particularly advantageous when
      an Event Receiver is behind a firewall or other network
      restriction that would prevent Push Delivery.  An Event Receiver
      may also use HTTP "Long-polling" to achieve real time event
      delivery.

   In the figure below, a possible distribution architecture is shown.
   This specification is only normatively concerned with the actual
   Security Event Transfer mechanism.  SCIM Service providers MAY choose
   to implement SET transfer directly, or they may use a method of
   allowing a single Event Publisher to assemble streams of events for
   transfer to a receiver.  Likewise, on the receiving side, the only
   normative requirement is to be able to receive events and implement
   storage of Events to local recovery needs.

Hunt, et al.              Expires 25 April 2024                [Page 25]
Internet-Draft           draft-ietf-scim-events             October 2023

         ┌───────────────┐  ┌───────────────┐    ┌───────────────┐
         │               │  │               │    │               │
         │ SCIM Server 1 │  │ SCIM Server 2 │ ...│ SCIM Server n │
         │               │  │               │    │               │
         └───────┬───────┘  └───────┬───────┘    └───────┬───────┘
                 │                  │                    │
         ┌───────▼──────────────────▼────────────────────▼───────┐
         │              Local Event Delivery System              │
         └───────────────────────────┬───────────────────▲───────┘
                                     │                   │
                            ┌────────▼────────┐   ┌──────┴───────┐
                            │                 │   │   Recovery   │
                            │ Event Publisher ◄───►    Buffer    │
                            │                 │   └──────────────┘
                            └────────┬────────┘
                        ┌──          │
                        │   ┌────────▼────────┐
                        │   │ SET Trans Txmtr │
                        │   │ (RFC 8935/8936) │
             Minimum    │   └────────┬────────┘
             Interop    │            │
             Requirement│            │
                        │   ┌────────▼────────┐   ┌──────────────┐
                        │   │  SET Trans Rcvr │   │     Event    │
                        │   │ (RFC 8935/8936) ├───►    Storage   │
                        │   └────────┬────────┘   └──────────────┘
                        └──          │
                            ┌────────▼────────┐
                            │ Receiver Domain │
                            │ Event Processor │
                            └────────┬────────┘
                                     │
                                     ▼

                                 Figure 22

   As Security Event Tokens are based on JWT tokens, it is possible to
   exchange events by a number of transfer mechanisms such as: XMPP
   [RFC6120], HTTP [RFC9113], and Message Buses (e.g.  [RFC3259], Apache
   Kafka [Kafka]).  For example, on the publishing side, a cluster or
   network of SCIM servers may publish events to a common SET publisher
   service for distribution to 1 or more receivers.  The Event Publisher
   MAY be incorporated directly into each SCIM Server, or a Local Event
   Delivery System might be used to collect events for an Event
   Publisher service for forwarding.  How this is done is up to the
   implementer.  This specification is only concerned with the
   interoperability of SET transfer between domains using [RFC8935] and
   [RFC8936].

Hunt, et al.              Expires 25 April 2024                [Page 26]
Internet-Draft           draft-ietf-scim-events             October 2023

   The SET Transfer specifications provide a short-term method of
   recovery to ensure SET Events are successfully transferred.  Once a
   receiving domain has successfully stored events to its own recovery
   needs, the receiving domain acknowledges the transfer of SET Events
   to the publisher using the method defined in [RFC8935] and [RFC8936].
   SET does not specify local server event recovery mechanisms, this is
   up to the service implementation within each domain.  This is done to
   enable cross-domain independence between domains.  As an example, a
   hosted SCIM service provider with a series of SCIM servers replicates
   through a proprietary system.  An enterprise customer who is the
   common client across both providers wants to establish a single
   administrative domain and wants to share SCIM change events between
   providers.  Each domain has its own SCIM implementation and its own
   local replication strategy.  The publishing domain issues events that
   the receiving domain picks up.  Once the receiving domain has
   processed the event, the receiving domains own internal replication
   and recovery takes over.  Because there is no need for the publishing
   domain to retain the event, it has the option to purge the event once
   the receiving domain has acknowledged it.  This may be particularly
   critical if a publishing domain has dozens or even thousands of event
   receiving domains each with their own sub-set of data.  Retaining all
   events for all receivers would become impractical.

3.1.  Security Event Token Signing and Encryption

   This specification uses Security Event Tokens as the message format
   for SCIM Events.  As SETs are based on JWT tokens [RFC7519], they can
   be transmitted insecurely, signed, or encrypted.  For more
   information see the JWT Cookbook specification [RFC7520] for
   examples.  The decision on whether to use JWS and JWE depends on
   operational considerations.  For each SCIM Feed relationship, it is
   up to deployers to decide on signing, encryption and algorithm
   requirements.  Deployers SHOULD be aware that too much emphasis on
   turning on every possible encryption feature may cause operational
   performance to suffer.  Deployers MUST weigh the security trade-offs
   of up-to-date SCIM services, vs. the potential information loss of an
   event.

   Unsecured
      Per Section 6 [RFC7519], tokens MAY be generated with
      {"alg":"none"}.  This mode speeds up processing and is best used
      in DBR scenarios.  Unencrypted tokens MUST be transferred over
      authenticated TLS layer encryption and SHOULD only be used in a
      restricted network environment.

   Signed
      JWS ([RFC7515]) signed SETs are useful when it is important to be
      able to verify the issuer of a SET as valid.  In addition, some

Hunt, et al.              Expires 25 April 2024                [Page 27]
Internet-Draft           draft-ietf-scim-events             October 2023

      systems MAY wish to validate the authenticity of the event in a
      review process which may occur at a later date.  While the content
      can be validated as originating from the correct issuer and is
      unmodified, the message contents remain unsecure.  Signed SETs
      MUST be transferred over encrypted transport.

   Encrypted
      JWE ([RFC7516]) are encrypted SETs and are useful when the
      transport mechanism is not fully secured (e.g. messages carried by
      a third party).  The use of JWEs ensures only the designated
      receiver can read the event and provides mutual authentication
      within the SET message itself.

3.2.  Point-to-Point Delivery Over HTTP

   Security Event Tokens MAY be delivered using push-based HTTP delivery
   [RFC8935], or pull-based HTTP Polling [RFC8936].  Both of these
   protocols define a method of transfer and acknowledgement to prevent
   loss-of-information and to provide re-transmission and recover.  The
   method of transfer is best decided by considering the following
   advantages and disadvantages in a production scenario:

   Push-based delivery has the following advantages:

   *  Message transfer is instant (when compared to using a common Event
      Publisher acting as a relay), and in high event frequency
      scenarios, HTTP connections can be kept open.

   *  Scales well when an SCIM Event Publisher has thousands of event
      receivers and TCP resources may be limited.

   *  Does not require events to be routed to a single publisher node.
      SCIM Events may be issued by SCIM Service Provider nodes where the
      transaction occurred.

   *  SCIM Events only need to be retained until they have been
      delivered to designated receivers.

   Push-delivery has the following disadvantages:

   *  A SCIM Event Publisher system needs authorization credentials
      enabling it to access the HTTP SCIM Event delivery endpoint.

   *  When synchronizing business data that is behind protected
      firewalls, a virtual network or other firewall policy may be
      required to allow external network based SCIM providers to deliver
      SCIM Events to internally hosted systems.

Hunt, et al.              Expires 25 April 2024                [Page 28]
Internet-Draft           draft-ietf-scim-events             October 2023

   Delivery by HTTP Polling has the following advantages:

   *  It is possible for a SCIM Event Receiver to use the same SCIM
      credentials it uses when access the normal SCIM Service Provider
      service defined by [RFC7644].

   *  Systems behind protected network boundaries can reach externally
      hosted systems without requiring special firewall or network
      configuration.

   *  Instantaneous transfer MAY be supported using HTTP Long-polling as
      described Section 2.1 of [RFC8936].

   Polling-based delivery has the following disadvantages:

   *  Long-polling requires the use of persistent connections for which
      TCP resources may be limited.  HTTP Long-polling is best used in
      scenarios when there are relatively few Event Receivers.

   *  The SCIM Event Publisher MUST retain events for the Event Receiver
      until delivered.

4.  Events Discovery Schema for Service Provider Configuration

   Section 5 of [RFC7643] defines SCIM Service Provider configuration
   schema.  This section defines additional attributes that enable a
   SCIM client to discover the additional capabilities defined by this
   specification.

   securityEvents
      A SCIM Complex attribute that specifies the available capabilities
      related to asynchronous Security Events based on [RFC8417].  This
      attribute is OPTIONAL and when absent indicates the SCIM server
      does not support or is not currently configured for Security
      Events.  The following sub-attributes are defined:

      asyncRequest
         A string value specifying one of the following:

         *  NONE indicates async SCIM requests defined in
            Section 2.6.1.1 are not supported;

         *  LONG indicates the SCIM Service Provider MAY complete
            asynchronously at its discretion (e.g.  based on a max wait
            time);

         *  REQUEST indicates the request SHALL complete asynchronously
            when requested by the SCIM Client.

Hunt, et al.              Expires 25 April 2024                [Page 29]
Internet-Draft           draft-ietf-scim-events             October 2023

      eventUris
         A multivalued string listing the SET Event URIs (defined in
         [RFC8417]) the server is capable of generating and deliverable
         via a SET Stream (see [RFC8935] and [RFC8936]).  This
         information is informational only.  Stream registration and
         configuration is out of scope of this specification.

5.  Security Considerations

   This specification depends on the Security Considerations for
   [RFC8417].

   The use of Json Web Encryption (JWE) [RFC7516] can impose performance
   limitations when used in high event frequency scenarios.  JWE is
   primarily useful only when the transfer of SETs involves an unsecured
   transfer method (e.g.  URL) that would not otherwise be protected by
   the transfer protocol (e.g.  SET Transfer over TLS [RFC8446]).

   For SCIM Provisioning events, the long-term series of changes may be
   critical to both sides.  As such Event Publishers SHOULD consider
   storing events for receivers for longer periods of time in the case
   of an extended SET Transfer service failure.  Similarly, Event
   Receivers MUST ensure events are persisted directly or indirectly
   sufficient to meet local recovery needs before acknowledging received
   SET Events.

   When SET Events are stored for future delivery or retained local
   recovery MUST be limited only to the parties needed to support
   recovery or SET forwarding.

   JWS [RFC7515] signed SET Events SHOULD be used to verify authenticity
   of the origin of a SET Event.  Validating event signatures is both
   useful on the initial transfer of SET Events, and may also be useful
   for auditing purposes.

   In operation, some SCIM resources such as SCIM Groups may have a high
   rate of change.  Implementors and operators SHOULD consider use of
   throttling techniques to balance immediacy and frequency.  For
   example, a large group whose members change dozens of times per
   second may not need discrete SET Patch Events per change.  Instead,
   issuing a single consolidated change per second or even minute may be
   beneficial to keeping Event Receivers up-to-date.  Likewise, a Co-
   ordinated Provisioning Event Receiver (Section 2.2), does not
   necessarily need to retrieve the full Group on every change request.
   It MAY choose to do lookups on a less frequent scale for
   reconciliation.

Hunt, et al.              Expires 25 April 2024                [Page 30]
Internet-Draft           draft-ietf-scim-events             October 2023

   When using Asynchronous SCIM Requests (see Section 2.6.1.1), and
   location returned in a SCIM Accepted response is a URI for retrieving
   the event result, the URI SHOULD be protected requiring an HTTP
   Authorization header.  Or in the alternative, the SET's retrieved
   SHOULD be encrypted in order to authenticate the receiver.  The
   retrieval endpoint SHOULD be protected

6.  Privacy Considerations

   This specification enables the sharing of information between
   domains.  The specification assumes that implementers and deployers
   are operating under one of the following scenarios:

   *  A common administrative domain where there is one administrative
      owner of the data.  In these cases the objective is to protect
      privacy and security of the owner and user data by keeping
      information systems co-ordinated and up-to-date.  For example, the
      domains decide to use Domain Based Replication mode in order to
      keep employee information synchronized.

   *  In a co-operative or co-ordinated relationship, parties have
      decided to share a limited amount of data and or signals for the
      benefits of their users.  Depending on end-user consent,
      information is shared on an as authorized and/or as needed basis.
      For example, the domains agree to use Co-ordinated Provision mode
      that exchanges things like account status, or specific minimal
      attribute information needed that must be fetched on request after
      receiving notice of a change.  This enables authorization to be
      verified each time data is transferred.

   In general the sharing of SCIM Event information falls within a pre-
   existing SCIM Client and Service Provider relationship.  In the case
   of SCIM Risk Signals Events, the existing relationship may need to be
   reviewed.  By their nature, however, SCIM Signals carry no personal
   information and aid parties in ensuring the protection of privacy
   information and account security.

   Privacy considerations of [RFC8417] MUST also be observed.

7.  IANA Considerations

7.1.  SCIM Async Txn Header Registration

   This specification registers the HTTP Set-txn field name in the "HTTP
   Field Name Registry" defined in Section 16.3.1 [RFC9110].

   Field name:
      Set-txn

Hunt, et al.              Expires 25 April 2024                [Page 31]
Internet-Draft           draft-ietf-scim-events             October 2023

   Status:
      Permanent

   Specification Document:
      this specification, Section 2.2 and Section 2.6.1.1.

   Comments:
      See also Section 2.2 [RFC8417] Security Event Tokens.

7.2.  Registration of the SCIM Event URIs Sub-Registry

   IANA will add the following new registry "SCIM Events Registry"
   within the "SCIM URN Sub-namespace" registry defined in Section 10.1
   [RFC7643] called the "SCIM Event URI Registry"

   Namespace ID:
      The sub-namespace ID of "event" is assigned within the "scim"
      namespace.

   Syntactic Structure:
      The Namespace Specific String (NSS) of all URNs that use the
      "event" Namespace ID SHALL have the following structure:

      "urn:ietf:params:scim:event:{class}:{name}:{other}

      The keywords have the following meaning:

      class
         The class of events which is one of: "feed", "prov", "sig", or
         "misc".

      name
         A US-ASCII string that conforms to URN syntax requirements (see
         [RFC8141]) and defines a descriptive event name (e.g.
         "create").

      other
         An optional US-ASCII string that conforms to URN syntax
         requirements (see [RFC8141]) and serves as an additional sub-
         category or qualifier.  For example "full" and "notice".

   Identifier Uniqueness Considerations:
      The designated contact shall be responsible for reviewing and
      enforcing uniqueness.

   Identifier Persistence Considerations:
      Once a name has been allocated it MUST NOT be re-allocated for a
      different purpose.  The rules provided for assignments of values

Hunt, et al.              Expires 25 April 2024                [Page 32]
Internet-Draft           draft-ietf-scim-events             October 2023

      within a sub-namespace MUST be constructed so that the meaning of
      values cannot change.  This registration mechanism is not
      appropriate for naming values whose meaning may change over time.

   Registration format:
      An event registration MUST include the following fields:

      *  Event Uri

      *  Descriptive Name

      *  Reference to event definition

      Initial values to be added to the SCIM Events Registry
      Section 7.3.

7.3.  Initial Events Registry

   Summary of Event URI registrations:

   +==========================================+===============+=======+
   |Event URI                                 |Name           |Ref.   |
   +==========================================+===============+=======+
   |urn:ietf:params:SCIM:event:feed:add       |Resource added |Section|
   |                                          |to Feed Event  |2.3.1  |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:feed:remove    |Remove resource|Section|
   |                                          |From Feed Event|2.3.2  |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:create:   |New Resource   |Section|
   |notice                                    |Event (notice  |2.4.1  |
   |                                          |only)          |       |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:create:   |New Resource   |Section|
   |full                                      |Event (full    |2.4.1  |
   |                                          |data)          |       |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:patch:    |Resource Patch |Section|
   |notice                                    |Event (notice  |2.4.2  |
   |                                          |only)          |       |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:patch:    |Resource Patch |Section|
   |full                                      |Event (full    |2.4.2  |
   |                                          |data)          |       |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:put:      |Resource Put   |Section|
   |notice                                    |Event (notice  |2.4.3  |
   |                                          |only)          |       |

Hunt, et al.              Expires 25 April 2024                [Page 33]
Internet-Draft           draft-ietf-scim-events             October 2023

   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:put:full  |Resource Put   |Section|
   |                                          |Event (full    |2.4.3  |
   |                                          |data)          |       |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:delete    |Resource       |Section|
   |                                          |Deleted Event  |2.4.4  |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:activate  |Resource       |Section|
   |                                          |Activated Event|2.4.5  |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:prov:deactivate|Resource       |Section|
   |                                          |Deactivated    |2.4.6  |
   |                                          |Event          |       |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:sig:authMethod |New            |Section|
   |                                          |authentication |2.5.1  |
   |                                          |method added   |       |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:sig:pwdReset   |Password Reset |Section|
   |                                          |Event          |2.5.2  |
   +------------------------------------------+---------------+-------+
   |urn:ietf:params:SCIM:event:misc:asyncResp |Async Request  |Section|
   |                                          |Completion     |2.6.1  |
   +------------------------------------------+---------------+-------+

                                 Table 1

8.  References

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [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,
              <https://www.rfc-editor.org/info/rfc3986>.

   [RFC7240]  Snell, J., "Prefer Header for HTTP", RFC 7240,
              DOI 10.17487/RFC7240, June 2014,
              <https://www.rfc-editor.org/info/rfc7240>.

Hunt, et al.              Expires 25 April 2024                [Page 34]
Internet-Draft           draft-ietf-scim-events             October 2023

   [RFC7515]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web
              Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
              2015, <https://www.rfc-editor.org/info/rfc7515>.

   [RFC7516]  Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
              RFC 7516, DOI 10.17487/RFC7516, May 2015,
              <https://www.rfc-editor.org/info/rfc7516>.

   [RFC7519]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
              <https://www.rfc-editor.org/info/rfc7519>.

   [RFC7643]  Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C.
              Mortimore, "System for Cross-domain Identity Management:
              Core Schema", RFC 7643, DOI 10.17487/RFC7643, September
              2015, <https://www.rfc-editor.org/info/rfc7643>.

   [RFC7644]  Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E.,
              and C. Mortimore, "System for Cross-domain Identity
              Management: Protocol", RFC 7644, DOI 10.17487/RFC7644,
              September 2015, <https://www.rfc-editor.org/info/rfc7644>.

   [RFC8141]  Saint-Andre, P. and J. Klensin, "Uniform Resource Names
              (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017,
              <https://www.rfc-editor.org/info/rfc8141>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8417]  Hunt, P., Ed., Jones, M., Denniss, W., and M. Ansari,
              "Security Event Token (SET)", RFC 8417,
              DOI 10.17487/RFC8417, July 2018,
              <https://www.rfc-editor.org/info/rfc8417>.

   [RFC9110]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/info/rfc9110>.

   [SUBID]    Ed, A. B., Scurtescu, M., and P. Jain, "Subject
              Identifiers for Security Event Tokens (Draft 18)", 24 June
              2023.

8.2.  Informative References

   [Kafka]    Apache Software Foundation, "Apache Kafka", 2017.

Hunt, et al.              Expires 25 April 2024                [Page 35]
Internet-Draft           draft-ietf-scim-events             October 2023

   [RFC3259]  Ott, J., Perkins, C., and D. Kutscher, "A Message Bus for
              Local Coordination", RFC 3259, DOI 10.17487/RFC3259, April
              2002, <https://www.rfc-editor.org/info/rfc3259>.

   [RFC6120]  Saint-Andre, P., "Extensible Messaging and Presence
              Protocol (XMPP): Core", RFC 6120, DOI 10.17487/RFC6120,
              March 2011, <https://www.rfc-editor.org/info/rfc6120>.

   [RFC7520]  Miller, M., "Examples of Protecting Content Using JSON
              Object Signing and Encryption (JOSE)", RFC 7520,
              DOI 10.17487/RFC7520, May 2015,
              <https://www.rfc-editor.org/info/rfc7520>.

   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/info/rfc8446>.

   [RFC8935]  Backman, A., Ed., Jones, M., Ed., Scurtescu, M., Ansari,
              M., and A. Nadalin, "Push-Based Security Event Token (SET)
              Delivery Using HTTP", RFC 8935, DOI 10.17487/RFC8935,
              November 2020, <https://www.rfc-editor.org/info/rfc8935>.

   [RFC8936]  Backman, A., Ed., Jones, M., Ed., Scurtescu, M., Ansari,
              M., and A. Nadalin, "Poll-Based Security Event Token (SET)
              Delivery Using HTTP", RFC 8936, DOI 10.17487/RFC8936,
              November 2020, <https://www.rfc-editor.org/info/rfc8936>.

   [RFC9113]  Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113,
              DOI 10.17487/RFC9113, June 2022,
              <https://www.rfc-editor.org/info/rfc9113>.

   [SSWG]     Tulshibagwale, A., Cappalli, T., Scurtescu, M., Backman,
              A., and J. Bradley, "OpenID Shared Signals and Events
              Framework Specification 1.0 - draft 01", 8 June 2021.

              Cappalli, T. and A. Tulshibagwale, "OpenID Continuous
              Access Evaluation Profile 1.0 - draft 02", 8 June 2021.

Appendix A.  Use Cases

   SCIM Events may be used in a number of ways.  The following non-
   normative sections describe some of the expected uses.

Hunt, et al.              Expires 25 April 2024                [Page 36]
Internet-Draft           draft-ietf-scim-events             October 2023

A.1.  Domain Based Replication

   The objective of "Domain Based Replication" events (DBR) is to
   synchronize resource changes between SCIM service providers in a
   common administrative domain.  In this mode, complete information
   about changes for resources are shared between replicas for immediate
   processing.

                       ┌────────────────┐
   ┌────────┐          │SCIM            │   ┌────────────────────────┐
   │Client A│          │Service Provider│   │Service Provider Replica│
   └───┬────┘          └───────┬────────┘   └───────────┬────────────┘
       │   "SCIM Operation"   ┌┴┐                       │
       │ ────────────────────>│ │                       │
       │                      │ │                       │
       │   "SCIM Response"    │ │                      ┌┴┐
       │ <────────────────────│ │                      │ │
       │                      └┬┘                      │ │
       │                       │  "Event SCIM:prov:<op>│ │
       │                       │  id:xyz"              │ │
       │                       │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─>│ │
       │                       │                       │ │
       │                       │                       │ │
       │                       │                       │ │────┐
                                    "Update local node"│ │    │
                                                       │ │<───┘
                                                       └┬┘

                Figure 23: Domain Based Replication Sequence

   From a security perspective, it is assumed that servers sharing DBR
   events are secured by a common access policy and all servers are
   required to be up-to-date.  From a Privacy Perspective, because all
   servers are in the same administrative domain, the primary objective
   is to keep individual service provider nodes or cluster synchronized.

A.2.  Co-ordinated Provisioning

   In "Co-ordinated Provisioning" (CP), SCIM resource change events
   perform the function of change notification without the need to
   provide raw data.  In any Event Publisher and Receiver relationship,
   the set of SCIM resources (e.g.  Users) that are linked or co-
   ordinated is managed within the context of an event feed and which
   MAY be a subset of the total set of resources on either side.  For
   example, an event feed could be limited to users who have consented
   to the sharing of information between domains.  To support
   capability, "feed" specific events are defined to indicate the
   addition and removal of SCIM resources from a feed.  For example,

Hunt, et al.              Expires 25 April 2024                [Page 37]
Internet-Draft           draft-ietf-scim-events             October 2023

   when a user consents to the sharing of information between domains,
   events about the User MAY be added to the feed between the Event
   Publisher and Receiver.

                  ┌────────────────┐  ┌──────────────┐  ┌─────────────┐
   ┌───────────┐  │SCIM            │  │Client A      │  │Co-op Action │
   │SCIM Client│  │Service Provider│  │Co-op Receiver│  │Endpoint     │
   └─────┬─────┘  └───────┬────────┘  └──────┬───────┘  └───────┬─────┘
         │ "SCIM Ope"    ┌┴┐                 │                  │
         │──────────────>│ │                 │                  │
         │               │ │                 │                  │
         │ "SCIM Resp"   │ │                ┌┴┐                 │
         │<──────────────│ │                │ │                 │
         │               │ │                │ │                 │
         │               │ │                │ │                 │
         │      ╔═══════╤╪═╪════════════════╪═╪═════════════════╪════╗
         │      ║ LOOP  ││ │                │ │                 │    ║
         │      ╟───────┘└┬┘ Event:         │ │                 │    ║
         │      ║         │   SCIM:prov:<op>│ │                 │    ║
         │      ║         │  id:xyz         │ │                 │    ║
         │      ║         │  ─ ─ ─ ─ ─ ─ ─ >│ │                 │    ║
         │      ║         │                 │ │                 │    ║
         │      ║         │    ╔════════════╧═╧══════════════╗  │    ║
         │      ║         │    ║Receiver may accumulate      ║  │    ║
         │      ║         │    ║events for periodic action.  ║  │    ║
         │      ║         │    ╚════════════╤═╤══════════════╝  │    ║
         │      ║         │ SCIM GET <id>   │ │                 │    ║
         │      ║         │ <───────────────│ │                 │    ║
         │      ║         │                 │ │                 │    ║
         │      ║         │ Filtered        │ │                 │    ║
         │      ║         │ Resource Resp   │ │                 │    ║
         │      ║         │ ───────────────>│ │                 │    ║
         │      ║         │                 │ │                 │    ║
         │      ║         │                 │ │ "Co-ord Action" │    ║
         │      ║         │                 │ │ ───────────────>│    ║
         │      ╚═════════╪═════════════════╪═╪═════════════════╪════╝

               Figure 24: Co-Ordinated Provisioning Sequence

   In CP mode, the receiver of an event must call back to the
   originating SCIM Service Provider (e.g. using a SCIM GET request) to
   reconcile the newly changed resource in order to obtain the changes.

   Co-ordinated provisioning has the following benefits:

Hunt, et al.              Expires 25 April 2024                [Page 38]
Internet-Draft           draft-ietf-scim-events             October 2023

   *  Differences in schema (e.g. attributes) between domains.  For
      example, a receiving domain may only be interested or only be
      allowed access to a few attributes (e.g. role based access data)
      to enable access to an application.

   *  Different Event Receivers MAY have differing needs access to
      information and thus be assigned varying access rights.  Minimal
      information events combined with call-backs for data allows data
      filtering to be applied.

   *  Receivers can take independent action.  For example deciding which
      attributes or resource lifecycle changes to accept.  For example,
      in the case of a conflict, a receiver can prioritize one domain
      source over another.

   *  A receiver MAY throttle or buffer changes rather than act
      immediately on a notification.  For example, for a frequently
      changing resource, the receiver MAY choose to make scheduled SCIM
      GET for resources that have been marked "dirty" by events received
      in the last scheduled cycle.

   A disadvantage of the CP approach is that it may be considered costly
   in the sense that each event received might trigger a call back to
   the event issuer.  This cost should be weighed against the cost
   producing filtered information in each event for each receiver.
   Further a receiver is not required to make a call-back on every
   provisioning event.

   It is assumed that an underlying relationship between domains exists
   that permits the exchange of personal information and credentials.
   For example the decision to perform SCIM provisioning operations at
   the SCIM Service Provider issuing change events, was previously
   authorized and appropriate confidentiality and privacy agreements
   have been met in cross-domain scenarios.  Examples of this might be
   services for hire by an employer or a specific consent from an end-
   user as part of a online authorization where individual consent was
   obtained.

   When sharing information between parties, CP Events minimize the
   information shared in each message requiring the Security Event
   Receiver to call back to the event publisher to retrieve more
   information if required.  In this way, the Event Publisher is able to
   have regular access to information through normal SCIM protocol
   access restrictions.

Hunt, et al.              Expires 25 April 2024                [Page 39]
Internet-Draft           draft-ietf-scim-events             October 2023

A.3.  Risk Signals

   The sharing of risk signals (RS) is used for the purpose of co-
   ordinating account change events between a SCIM Service Provider and
   another related security service.  For example, when a password or
   other authentication factor has changed, a receiving security system
   can choose to terminate current User sessions to force a re-
   authentication against the modified User resource.

   These signals MAY also include those described in the OpenID Shared
   Signals Working Group Specifications [SSWG].

   These events are intended for receivers where there is a prior
   relationship on behalf of the users described in the SCIM Service
   Provider.  The intent of sharing information about security events is
   for the purpose of securing a user account and ensuring privacy.

Appendix B.  Acknowledgments

   Thanks to Morteza Ansari who contributed significantly to draft-hunt-
   idevent-scim-00, upon which this draft is based.

   The editor would like to thank the participants in the SCIM working
   group and the id-event list for their support of this specification.

Appendix C.  Change Log

   Draft 00 - PH - First WG Draft

   Draft 01 - PH - Moved non-normative sections to Appendix, Security
   and Privacy Considerations

   Draft 02 - PH - Clarifications on Async Events, IANA Considerations

   Draft 03 - PH - Fixed Header Field registration to
   RFC9110."Preference-Applied" header in async response.  Support for
   Async Bulk requests.  Added IANA SCIM Event Registry

Authors' Addresses

   Phil Hunt (editor)
   Independent Identity Inc
   Email: phil.hunt@independentid.com

   Nancy Cam-Winget
   Cisco Systems
   Email: ncamwing@cisco.com

Hunt, et al.              Expires 25 April 2024                [Page 40]
Internet-Draft           draft-ietf-scim-events             October 2023

   Mike Kiser
   Sailpoint Technologies
   Email: mike.kiser@sailpoint.com

   Jen Schreiber
   Workday Incorporated
   Email: jennifer.winer@workday.com

Hunt, et al.              Expires 25 April 2024                [Page 41]