Internet-Draft draft-ietf-scim-events July 2023
Hunt, et al. Expires 11 January 2024 [Page]
Workgroup:
SCIM
Internet-Draft:
draft-ietf-scim-events
Published:
Intended Status:
Standards Track
Expires:
Authors:
P. Hunt, Ed.
IndependentId
N. Cam-Winget
Cisco Systems
M. Kiser
Sailpoint

SCIM Profile for Security Event Tokens

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 11 January 2024.

Table of Contents

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.

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:

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.
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.

{
     "iss": "issuer.example.com",
     "iat": 1508184845,
     "aud": "aud.example.com",
     "sub_id": {
        "format": "scim",
        "uri": "/Users/2b2f880af6674ac284bae9381673d462",
        "externalId": "[email protected]"
     },
     "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 attributes 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.

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 specifications 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

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.

{
  "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.

{
  "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":"[email protected]"}
        ],
        "userName":"jdoe",
        "name":{
          "givenName":"John",
          "familyName":"Doe"
        }
      }
    }
  }
}
Figure 4: Example SCIM Create (Full)
{
  "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.

{
  "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)
{
  "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.

{
  "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":"[email protected]"},
          {"value":"[email protected]"}
        ]
      }
    }
  },
  "iat": 1458505044,
  "iss":"https://scim.example.com",
  "aud":[
   "https://scim.example.com/Feeds/98d52461fa5bbc879593b7754"
  ]
}
Figure 8: Example SCIM Put Event (Full)
{
  "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

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

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

2.6. Miscellaneous Events

This section defines events related miscellaneous events such as Asynchronous Request completion that have 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. The value SHALL correspond to a future Security Event Token to be received whose "txn" claim SHALL match. 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":

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":"[email protected]"
    }
  ]
}
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
Location:
  "/Users/2819c223-7f76-453a-919d-413861904646"
Figure 15
2.6.1.2. 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

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.

┌───────────────┐  ┌───────────────┐    ┌───────────────┐
│               │  │               │    │               │
│ 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 17

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].

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 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.

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.
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.

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:

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 section registers the HTTP 'set-txn' header field in the "Permanent Message Header Field Names" registry defined in [RFC3864].

Header field name:
Set-txn
Applicable Protocol:
HTTP
Status:
Standard
Author:
IETF
Specification Document:
this specification, Section 2.2 and Section 2.6.1.1.
Related information:
See also: Section 2.2 [RFC8417].

7.2. SCIM Events Registry

This section registers a new type called "event" in the SCIM Namespace registry found in Section 2 in the SCIM registry as per Section 10.2.1 [RFC7643].

This new event namespace shall take the structure: urn:ietf:params:scim:event:{class}:{name}:{other}

Schema URI:
SeeSection 2.
Schema Name:
See corresponding names underSection 2.
Intended ResourceType:
N/A. Events are not intended to be persisted in SCIM and will be used with Security Event Tokens [RFC8417].
Purpose:
See each description inSection 2.
Single-valued Attributes:
None.
Multi-valued Attributes:
All schemas in this specification share the same attributes. SeeSection 2.2.

Summary of schema URI registrations:

Table 1
Schema URI Name Ref.
urn:ietf:params:SCIM:event:feed:add Resource added to Feed Event Section 2.3.1
urn:ietf:params:SCIM:event:feed:remove Remove resouce From Feed Event Section 2.3.2
urn:ietf:params:SCIM:event:prov:create: notice New Resource Event (notice only) Section 2.4.1
urn:ietf:params:SCIM:event:prov:create: full New Resource Event (full data) Section 2.4.1
urn:ietf:params:SCIM:event:prov:patch: notice Resource Patch Event (notice only) Section 2.4.2
urn:ietf:params:SCIM:event:prov:patch: full Resource Patch Event (full data) Section 2.4.2
urn:ietf:params:SCIM:event:prov:put: notice Resource Put Event (notice only) Section 2.4.3
urn:ietf:params:SCIM:event:prov:put:full Resource Put Event (full data) Section 2.4.3
urn:ietf:params:SCIM:event:prov:delete Resource Deleted Event Section 2.4.4
urn:ietf:params:SCIM:event:prov:activate Resource Activated Event Section 2.4.5
urn:ietf:params:SCIM:event:prov:deactivate Resource Deactivated Event Section 2.4.6
urn:ietf:params:SCIM:event:sig:authMethod New authentication method added Section 2.5.1
urn:ietf:params:SCIM:event:sig:pwdReset Password Reset Event Section 2.5.2

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, , <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, , <https://www.rfc-editor.org/info/rfc3986>.
[RFC7240]
Snell, J., "Prefer Header for HTTP", RFC 7240, DOI 10.17487/RFC7240, , <https://www.rfc-editor.org/info/rfc7240>.
[RFC7515]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, , <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516]
Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, , <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, , <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, , <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, , <https://www.rfc-editor.org/info/rfc7644>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <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, , <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, , <https://www.rfc-editor.org/info/rfc9110>.
[SUBID]
Ed, A. B., Scurtescu, M., and P. Jain, "Subject Identifiers for Security Event Tokens (Draft 18)", .

8.2. Informative References

[Kafka]
Apache Software Foundation, "Apache Kafka", .
[RFC3259]
Ott, J., Perkins, C., and D. Kutscher, "A Message Bus for Local Coordination", RFC 3259, DOI 10.17487/RFC3259, , <https://www.rfc-editor.org/info/rfc3259>.
[RFC3864]
Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, DOI 10.17487/RFC3864, , <https://www.rfc-editor.org/info/rfc3864>.
[RFC6120]
Saint-Andre, P., "Extensible Messaging and Presence Protocol (XMPP): Core", RFC 6120, DOI 10.17487/RFC6120, , <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, , <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, , <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, , <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, , <https://www.rfc-editor.org/info/rfc8936>.
[RFC9113]
Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, DOI 10.17487/RFC9113, , <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", .
Cappalli, T. and A. Tulshibagwale, "OpenID Continuous Access Evaluation Profile 1.0 - draft 02", .

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.

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.

Client A SCIM Service Provider Service Provider Replica [1] SCIM Operation [2] SCIM Response [3] Event SCIM:prov:<op> id:xyz [4] Update local node
Figure 18: 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, 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 SCIM Service Provider Client A Co-op Receiver Co-op Action Endpoint loop [1] SCIM Operation [2] SCIM Response [3] Event SCIM:prov:<op> id:xyz [4] SCIM GET <id> [5] Filtered Resource Response [6] Co-ordinated Action Receiver may accumulate events for periodic action.
Figure 19: 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:

  • 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 regular access to information through normal SCIM protocol access restrictions.

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

Authors' Addresses

Phil Hunt (editor)
Independent Identity Inc
Nancy Cam-Winget
Cisco Systems
Mike Kiser
Sailpoint Technologies